Class UnauthorizedException

java.lang.Object

java.lang.Throwable

java.lang.Exception

ai.redouble.nucleo.harness.errors.LLMReadableCheckedException

ai.redouble.nucleo.harness.errors.UncorrectableLLMException

ai.redouble.nucleo.harness.errors.UnauthorizedException

All Implemented Interfaces:

LLMReadable, LLMReadableException, Serializable

Direct Known Subclasses:

Http401Exception, Http403Exception

public class UnauthorizedException
extends UncorrectableLLMException

Exception thrown when an API or service rejects the request due to authentication or authorization failure (HTTP 401/403).

This is an uncorrectable exception - the LLM cannot fix authentication issues. The LLM should try an alternative tool or data source, or explain the limitation to the user.

Distinct from PermissionDeniedException:

• UnauthorizedException - External API rejected our credentials (HTTP 401/403). API key expired, invalid, missing, or insufficient scope.
• PermissionDeniedException - Internal permission check. User lacks access to a feature or resource within our system.

Usage Example:

if (response.statusCode() == 401 || response.statusCode() == 403) {
    throw new UnauthorizedException("EPO OPS", "API key rejected (HTTP " + response.statusCode() + ")");
}

LLM sees:

Access denied to EPO OPS: API key rejected (HTTP 401)
[This error is not correctable - consider an alternative approach]

Since:

0.1 (2026-02-26)

Author:

Andrey Santrosyan

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
UnauthorizedException(String serviceName, String reason)	Constructs an unauthorized exception.
UnauthorizedException(String serviceName, String reason, Throwable cause)	Constructs an unauthorized exception with a cause.

Method Summary

Modifier and Type	Method	Description
String	getLLMMessage()	Returns a clean, actionable error message suitable for LLM understanding.
String	getReason()
String	getServiceName()

Methods inherited from class UncorrectableLLMException

explainToLLM, isCorrectable

Methods inherited from class LLMReadableCheckedException

unwrap, wrapWithContext

Methods inherited from class Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

UnauthorizedException

public UnauthorizedException(String serviceName,
 String reason)

Constructs an unauthorized exception.

Parameters:

serviceName - the external service that rejected the request

reason - description of the auth failure (e.g., "API key expired", "HTTP 403")

UnauthorizedException

public UnauthorizedException(String serviceName,
 String reason,
 Throwable cause)

Constructs an unauthorized exception with a cause.

Parameters:

serviceName - the external service that rejected the request

reason - description of the auth failure

cause - the underlying cause

Method Details

getLLMMessage

public String getLLMMessage()

Description copied from class: LLMReadableCheckedException

Returns a clean, actionable error message suitable for LLM understanding.

This message should:

• Explain what went wrong in plain language
• Be specific about which parameter or input caused the problem
• Suggest how to fix the issue when possible
• Avoid stack traces, exception types, or code references

Good examples:

• "Maximum result limit is 100. Please reduce maxResults parameter to 100 or less."
• "Parameter 'dateFrom' has invalid format '2024-13-01'. Use ISO 8601 format: YYYY-MM-DD."
• "Permission denied to access system clock. This tool requires elevated privileges."

Bad examples:

• "NullPointerException at line 247"
• "Error code -1"
• "Invalid input" (not specific enough)

Specified by:

getLLMMessage in interface LLMReadable

Specified by:

getLLMMessage in class LLMReadableCheckedException

Returns:

clean, actionable error message for LLM

getServiceName

public String getServiceName()

getReason

public String getReason()