The errors of AI services (Effect's AiError).
Every AI operation fails with one AiError: the module and method
that failed and a reason saying why (a rate limit, a bad request, an
invalid tool result, ...). Recover from one kind of reason with
fx.catch_reason(AiError, RateLimitError, handler); is_retryable and
retry_after read the reason.
Each error is a schema: its wire form is Effect's (camelCase keys with a
_tag), so errors sent to a model as tool results, or stored in a chat
history, read the same in both libraries.
Values#
| Attribute | Type | Description |
|---|---|---|
HTTP_RESPONSE_DETAILS | StructSchema[HttpResponseDetails, Never, Never] | |
HTTP_CONTEXT | StructSchema[HttpContext, Never, Never] | |
USAGE_INFO | StructSchema[UsageInfo, Never, Never] | |
PROVIDER_METADATA | RecordSchema[str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None, str, bool | int | float | str | Sequence[bool | int | float | str | ... | Mapping[str, JsonValue] | None] | Mapping[str, bool | int | float | str | Sequence[JsonValue] | ... | None] | None, Never, Never] | Effect's |
REASONS | tuple[type[AiErrorReason], ...] | |
AI_ERROR_REASON | S.Bottom[AnyReason, Mapping[str, object]] | The schema of every reason (Effect's |
Types#
| Type | Definition | Description |
|---|---|---|
ProviderMetadata | type ProviderMetadata = dict[str, JsonValue] | Provider-specific details, by provider name. |
AuthenticationKind | type AuthenticationKind = Literal['InvalidKey', 'ExpiredKey', 'MissingKey', 'InsufficientPermissions', 'Unknown'] | |
AnyReason | type AnyReason = RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InvalidResponseError | InternalProviderError | NetworkError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError |
Classes#
Functions#
make#
make(*, module, method, reason) -> AiError| Parameter | Type | Description |
|---|---|---|
module | str | |
method | str | |
reason | AnyReason |
Returns AiError
def make(*, module: str, method: str, reason: AnyReason) -> AiError:
return AiError(module=module, method=method, reason=reason)is_ai_error#
is_ai_error(u) -> bool| Parameter | Type | Description |
|---|---|---|
u | object |
Returns bool
def is_ai_error(u: object) -> bool:
return isinstance(u, AiError)is_ai_error_reason#
is_ai_error_reason(u) -> bool| Parameter | Type | Description |
|---|---|---|
u | object |
Returns bool
def is_ai_error_reason(u: object) -> bool:
return isinstance(u, AiErrorReason)reason_from_http_status#
reason_from_http_status(*, status, body=None, http=None, metadata=None, description=None) -> AnyReasonThe reason an HTTP status stands for (400 a bad request, 401 /
403 refused credentials, 429 a rate limit, 5xx a provider failure).
| Parameter | Type | Description |
|---|---|---|
status | int | |
body | object = None | |
http | HttpContext | None = None | |
metadata | ProviderMetadata | None = None | |
description | str | None = None |
Returns AnyReason
def reason_from_http_status(
*,
status: int,
body: object = None,
http: HttpContext | None = None,
metadata: ProviderMetadata | None = None,
description: str | None = None,
) -> AnyReason:
"""The reason an HTTP ``status`` stands for (400 a bad request, 401 /
403 refused credentials, 429 a rate limit, 5xx a provider failure)."""
meta: ProviderMetadata = metadata or {}
desc = description or None
match status:
case 400:
return InvalidRequestError(description=desc, metadata=meta, http=http)
case 401:
return AuthenticationError(
kind="InvalidKey", description=desc, metadata=meta, http=http
)
case 403:
return AuthenticationError(
kind="InsufficientPermissions", description=desc, metadata=meta, http=http
)
case 429:
return RateLimitError(metadata=meta, http=http)
case _ if status >= 500:
return InternalProviderError(
description=desc or "Server error", metadata=meta, http=http
)
case _:
return UnknownError(description=desc, metadata=meta, http=http)build_error_description#
build_error_description(*, status, message, method, url, body, error_code=None, error_type=None, request_id=None) -> strA one-line description of a failed HTTP call (Effect's
buildErrorDescription).
| Parameter | Type | Description |
|---|---|---|
status | int | |
message | str | None | |
method | str | |
url | str | |
body | str | None | |
error_code | str | int | None = None | |
error_type | str | None = None | |
request_id | str | None = None |
Returns str
def build_error_description(
*,
status: int,
message: str | None,
method: str,
url: str,
body: str | None,
error_code: str | int | None = None,
error_type: str | None = None,
request_id: str | None = None,
) -> str:
"""A one-line description of a failed HTTP call (Effect's
``buildErrorDescription``)."""
parts = [message or f"HTTP {status}", f"({method} {url})"]
if error_code:
parts.append(f"[code: {error_code}]")
elif error_type:
parts.append(f"[type: {error_type}]")
if request_id:
parts.append(f"[requestId: {request_id}]")
if not message and body:
parts.append(f"Response: {body[:200] + '...' if len(body) > 200 else body}")
return " ".join(parts)