AiError
Defines shared errors for AI operations.
AiError records where a failure happened and stores the detailed reason in a reason field. Those reasons cover transport problems, provider responses, rate limits, authentication, content policy failures, invalid requests, invalid output, unsupported schemas, tool failures, invalid user input, and unknown failures. This module also includes metadata schemas, guards, constructors, and helpers for converting HTTP response information into AI error reasons.
Configuration
AuthenticationErrorMetadata interface
Added in v4.0.0
Source
Signature
interface AuthenticationErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}ContentPolicyErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to ContentPolicyError.
Signature
interface ContentPolicyErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}InternalProviderErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to InternalProviderError.
Signature
interface InternalProviderErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}InvalidOutputErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to InvalidOutputError.
Signature
interface InvalidOutputErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}InvalidRequestErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to InvalidRequestError.
Signature
interface InvalidRequestErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}QuotaExhaustedErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to QuotaExhaustedError.
Signature
interface QuotaExhaustedErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}RateLimitErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to RateLimitError.
Signature
interface RateLimitErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}StructuredOutputErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to StructuredOutputError.
Signature
interface StructuredOutputErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}UnknownErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to UnknownError.
Signature
interface UnknownErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}UnsupportedSchemaErrorMetadata interface
Added in v4.0.0
Source
Provider-specific metadata attached to UnsupportedSchemaError.
Signature
interface UnsupportedSchemaErrorMetadata extends ProviderMetadata { [key: string]: MutableJson;}Constructors
Creates an AiError with the given reason.
Signature
declare function make(params: { readonly method: string; readonly module: string; readonly reason: AiErrorReason;}): AiError;reasonFromHttpStatus
Added in v4.0.0
Source
Maps HTTP status codes to semantic error reasons.
When to use
Use as the base mapping when provider packages translate HTTP status codes into provider-specific error reasons.
Signature
declare function reasonFromHttpStatus(params: { readonly body?: unknown; readonly description?: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: MutableJson; }; readonly status: number;}): AiErrorReasonErrors
AiErrorReason type
Added in v4.0.0
Source
Union type of all semantic error reasons that can occur during AI operations.
Details
Every reason carries a semantic _tag, a human-readable message, and an isRetryable getter. Provider-facing reasons may also include retry timing, provider metadata, usage information, or HTTP context.
Signature
type AiErrorReason = | RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InternalProviderError | NetworkError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError;AuthenticationError
Added in v4.0.0
Source
Error indicating authentication or authorization failure.
Details
Authentication errors are never retryable without credential changes.
Signature
declare class AuthenticationError extends { readonly _tag: "AuthenticationError"; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly kind: "Unknown" | "MissingKey" | "InvalidKey" | "ExpiredKey" | "InsufficientPermissions"; readonly metadata: { [key: string]: MutableJson; } & AuthenticationErrorMetadata;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "AuthenticationError"; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly kind: "Unknown" | "MissingKey" | "InvalidKey" | "ExpiredKey" | "InsufficientPermissions"; readonly metadata?: { [key: string]: unknown; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}ContentPolicyError
Added in v4.0.0
Source
Error indicating content policy violation.
Details
Content policy errors are never retryable without content changes.
Signature
declare class ContentPolicyError extends { readonly _tag: "ContentPolicyError"; readonly description: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata: { [key: string]: MutableJson; } & ContentPolicyErrorMetadata;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "ContentPolicyError"; readonly description: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: unknown; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}InternalProviderError
Added in v4.0.0
Source
Error indicating the AI provider experienced an internal error.
Details
Internal provider errors are typically transient and are retryable.
Signature
declare class InternalProviderError extends { readonly _tag: "InternalProviderError"; readonly description: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata: { [key: string]: MutableJson; } & InternalProviderErrorMetadata;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "InternalProviderError"; readonly description: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: unknown; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}InvalidOutputError
Added in v4.0.0
Source
Error indicating failure to parse or validate LLM output.
Details
Invalid output errors are retryable since LLM outputs are non-deterministic.
Signature
declare class InvalidOutputError extends { readonly _tag: "InvalidOutputError"; readonly description: string; readonly metadata: { [key: string]: MutableJson; } & InvalidOutputErrorMetadata; readonly usage?: { readonly completionTokens?: number; readonly promptTokens?: number; readonly totalTokens?: number; };} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "InvalidOutputError"; readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly usage?: { readonly completionTokens?: number; readonly promptTokens?: number; readonly totalTokens?: number; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string; static fromSchemaError(error: SchemaError): InvalidOutputError;}InvalidRequestError
Added in v4.0.0
Source
Error indicating the request had invalid or malformed parameters.
Details
Invalid request errors require fixing the request and are not retryable.
Signature
declare class InvalidRequestError extends { readonly _tag: "InvalidRequestError"; readonly constraint?: string; readonly description?: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata: { [key: string]: MutableJson; } & InvalidRequestErrorMetadata; readonly parameter?: string;} & YieldableError<this> { constructor(...args: [props?: { readonly _tag?: "InvalidRequestError"; readonly constraint?: string; readonly description?: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: unknown; }; readonly parameter?: string; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}InvalidToolResultError
Added in v4.0.0
Source
Error indicating the tool handler returned an invalid result that does not match the tool's schema.
Details
This error is not retryable because invalid results indicate a bug in the tool handler implementation.
Signature
declare class InvalidToolResultError extends { readonly _tag: "InvalidToolResultError"; readonly description: string; readonly toolName: string;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "InvalidToolResultError"; readonly description: string; readonly toolName: string; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}InvalidUserInputError
Added in v4.0.0
Source
Error indicating the user provided invalid input in their prompt.
Details
This error is raised when the prompt contains content that is structurally valid but not supported by the provider (e.g., unsupported media types, unsupported file formats, etc.).
Signature
declare class InvalidUserInputError extends { readonly _tag: "InvalidUserInputError"; readonly description: string;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "InvalidUserInputError"; readonly description: string; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}NetworkError
Added in v4.0.0
Source
Error indicating a network-level failure before receiving a response.
Details
This error is raised when issues arise before receiving an HTTP response, such as network connectivity problems, request encoding issues, or invalid URLs.
Signature
declare class NetworkError extends { readonly _tag: "NetworkError"; readonly description?: string; readonly reason: "TransportError" | "EncodeError" | "InvalidUrlError"; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; };} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "NetworkError"; readonly description?: string; readonly reason: "TransportError" | "EncodeError" | "InvalidUrlError"; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string; static fromRequestError(error: RequestError): NetworkError;}QuotaExhaustedError
Added in v4.0.0
Source
Error indicating account or billing limits have been reached.
Details
Quota exhausted errors are not retryable without user action.
Signature
declare class QuotaExhaustedError extends { readonly _tag: "QuotaExhaustedError"; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata: { [key: string]: MutableJson; } & QuotaExhaustedErrorMetadata; readonly resetAt?: Utc;} & YieldableError<this> { constructor(...args: [props?: { readonly _tag?: "QuotaExhaustedError"; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: unknown; }; readonly resetAt?: Utc; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}RateLimitError
Added in v4.0.0
Source
Error indicating the request was rate limited.
Details
Rate limit errors are always retryable. When retryAfter is provided, callers should wait that duration before retrying.
Signature
declare class RateLimitError extends { readonly _tag: "RateLimitError"; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata: { [key: string]: MutableJson; } & RateLimitErrorMetadata; readonly retryAfter?: Duration;} & YieldableError<this> { constructor(...args: [props?: { readonly _tag?: "RateLimitError"; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: unknown; }; readonly retryAfter?: Duration; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}StructuredOutputError
Added in v4.0.0
Source
Error indicating the LLM generated text that does not conform to the requested structured output schema.
Details
Structured output errors are retryable since LLM outputs are non-deterministic.
Signature
declare class StructuredOutputError extends { readonly _tag: "StructuredOutputError"; readonly description: string; readonly metadata: { [key: string]: MutableJson; } & StructuredOutputErrorMetadata; readonly responseText: string; readonly usage?: { readonly completionTokens?: number; readonly promptTokens?: number; readonly totalTokens?: number; };} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "StructuredOutputError"; readonly description: string; readonly metadata?: { [key: string]: unknown; }; readonly responseText: string; readonly usage?: { readonly completionTokens?: number; readonly promptTokens?: number; readonly totalTokens?: number; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string; static fromSchemaError(error: SchemaError, responseText: string): StructuredOutputError;}ToolConfigurationError
Added in v4.0.0
Source
Error indicating a provider-defined tool was configured with invalid arguments.
Details
This error is not retryable because it indicates a programming error in the tool configuration that must be fixed in code.
Signature
declare class ToolConfigurationError extends { readonly _tag: "ToolConfigurationError"; readonly description: string; readonly toolName: string;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "ToolConfigurationError"; readonly description: string; readonly toolName: string; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}ToolkitRequiredError
Added in v4.0.0
Source
Error indicating an operation requires a toolkit but none was provided.
Details
This error occurs when tool approval responses are present in the prompt but no toolkit was provided to resolve them.
Signature
declare class ToolkitRequiredError extends { readonly _tag: "ToolkitRequiredError"; readonly description?: string; readonly pendingApprovals: readonly Array<string>;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "ToolkitRequiredError"; readonly description?: string; readonly pendingApprovals: readonly Array<string>; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}ToolNotFoundError
Added in v4.0.0
Source
Error indicating the model requested a tool that doesn't exist in the toolkit.
Details
This error is retryable because the model may self-correct when provided with the list of available tools.
Signature
declare class ToolNotFoundError extends { readonly _tag: "ToolNotFoundError"; readonly availableTools: readonly Array<string>; readonly toolName: string;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "ToolNotFoundError"; readonly availableTools: readonly Array<string>; readonly toolName: string; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}ToolParameterValidationError
Added in v4.0.0
Source
Error indicating the model's tool call parameters failed schema validation.
Details
This error is retryable because the model may correct its parameters on subsequent attempts.
Signature
declare class ToolParameterValidationError extends { readonly _tag: "ToolParameterValidationError"; readonly description: string; readonly toolName: string; readonly toolParams: Json;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "ToolParameterValidationError"; readonly description: string; readonly toolName: string; readonly toolParams: unknown; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}ToolResultEncodingError
Added in v4.0.0
Source
Error indicating the tool result cannot be encoded for sending back to the model.
Details
This error is not retryable because encoding failures indicate a bug in the tool schema definitions.
Signature
declare class ToolResultEncodingError extends { readonly _tag: "ToolResultEncodingError"; readonly description: string; readonly toolName: string; readonly toolResult: unknown;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "ToolResultEncodingError"; readonly description: string; readonly toolName: string; readonly toolResult: unknown; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}UnknownError
Added in v4.0.0
Source
Error data for unknown or unexpected AI failures.
Details
Unknown errors are not retryable by default since the cause is unknown.
Signature
declare class UnknownError extends { readonly _tag: "UnknownError"; readonly description?: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata: { [key: string]: MutableJson; } & UnknownErrorMetadata;} & YieldableError<this> { constructor(...args: [props?: { readonly _tag?: "UnknownError"; readonly description?: string; readonly http?: { readonly body?: string; readonly request: { readonly hash?: string; readonly headers: { [key: string]: string | Redacted<string>; }; readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE"; readonly url: string; readonly urlParams: readonly Array<readonly [string, string]>; }; readonly response?: { readonly headers: { [key: string]: string | Redacted<string>; }; readonly status: number; }; }; readonly metadata?: { [key: string]: unknown; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}UnsupportedSchemaError
Added in v4.0.0
Source
Error indicating a codec transformer rejected a schema because it contains unsupported constructs.
Details
Unsupported schema errors are not retryable because they indicate a programmer error where the schema is incompatible with the provider.
Signature
declare class UnsupportedSchemaError extends { readonly _tag: "UnsupportedSchemaError"; readonly description: string; readonly metadata: { [key: string]: MutableJson; } & UnsupportedSchemaErrorMetadata;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "UnsupportedSchemaError"; readonly description: string; readonly metadata?: { [key: string]: unknown; }; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/Reason": "~effect/unstable/ai/AiError/Reason"; isRetryable: boolean; message: string;}Guards
Type guard to check if a value is an AiError.
Signature
declare function isAiError(u: unknown): u is AiError;isAiErrorReason
Added in v4.0.0
Source
Type guard to check if a value is an AiErrorReason.
Signature
declare function isAiErrorReason(u: unknown): u is AiErrorReason;Models
ProviderMetadata type
Added in v4.0.0
Source
Type of provider-specific metadata attached to AI error reasons.
Details
Metadata is keyed by provider name, and each provider value is either mutable JSON metadata or null.
Signature
type ProviderMetadata = typeof ProviderMetadata.Type;Schemas
Schema for the top-level AI error wrapper using the reason pattern.
When to use
Use when you need AI errors that can be handled by semantic reason with Effect.catchReason.
Details
This error stores module and method context, the semantic reason, and delegates isRetryable and retryAfter to the underlying reason.
Signature
declare class AiError extends { readonly _tag: "AiError"; readonly method: string; readonly module: string; readonly reason: NetworkError | RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InternalProviderError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError;} & YieldableError<this> { constructor(...args: [props: { readonly _tag?: "AiError"; readonly method: string; readonly module: string; readonly reason: NetworkError | RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InternalProviderError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError; }, options?: MakeOptions]); readonly "~effect/unstable/ai/AiError/AiError": "~effect/unstable/ai/AiError/AiError"; readonly cause: NetworkError | RateLimitError | QuotaExhaustedError | AuthenticationError | ContentPolicyError | InvalidRequestError | InternalProviderError | InvalidOutputError | StructuredOutputError | UnsupportedSchemaError | UnknownError | ToolNotFoundError | ToolParameterValidationError | InvalidToolResultError | ToolResultEncodingError | ToolConfigurationError | ToolkitRequiredError | InvalidUserInputError; isRetryable: boolean; message: string; retryAfter: Duration | undefined;}AiErrorEncoded type
Added in v4.0.0
Source
The encoded (serialized) form of an AiError.
Signature
type AiErrorEncoded = (typeof AiError)["Encoded"];AiErrorReason
Added in v4.0.0
Source
Schema for validating and parsing AI error reasons.
When to use
Use when decoding or validating unknown AI error reason values with Schema.
Details
This runtime schema is the union of the concrete AI error reason classes.
See
isAiErrorReasonfor checking an existing value without Schema decoding
Signature
declare const AiErrorReason: Union< [ typeof RateLimitError, typeof QuotaExhaustedError, typeof AuthenticationError, typeof ContentPolicyError, typeof InvalidRequestError, typeof InternalProviderError, typeof NetworkError, ]>;HttpContext
Added in v4.0.0
Source
Schema for the combined HTTP context used in error reporting.
When to use
Use to attach request details, optional response details, and optional body text to AI provider errors.
Details
Includes the required request details plus optional response details and raw response body.
See
HttpRequestDetailsfor captured request detailsHttpResponseDetailsfor captured response details
Signature
declare const HttpContext: Struct<{ readonly body: optional<String>; readonly request: Struct<{ readonly hash: optional<String>; readonly headers: $Record<String, Union<readonly [String, Redacted<String>]>>; readonly method: Literals< readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE"] >; readonly url: String; readonly urlParams: $Array<Tuple<readonly [String, String]>>; }>; readonly response: optional< Struct<{ readonly headers: $Record<String, Union<readonly [String, Redacted<String>]>>; readonly status: Int; }> >;}>;ProviderMetadata
Added in v4.0.0
Source
Schema for provider-specific metadata which can be attached to error reasons.
Details
Provider-specific metadata is namespaced by provider name. Each provider value can contain arbitrary mutable JSON metadata or null.
Signature
declare const ProviderMetadata: Schema.$Record< Schema.String, Schema.NullOr<Schema.Codec<Schema.MutableJson>>>;Schema for token usage information from AI operations.
Details
Schema for optional provider-reported token counts for prompt tokens, completion tokens, and total tokens.
Signature
declare const UsageInfo: Struct<{ readonly completionTokens: optional<Int>; readonly promptTokens: optional<Int>; readonly totalTokens: optional<Int>;}>;
Provider-specific metadata attached to
AuthenticationError.