errors.ts

Source: sdks/typescript/packages/sdk/src/errors.ts. Back to the TypeScript SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Interface ErrorEnvelope

JSON error body of the API: code, message, localized messages, details and request id under error.

Fields:

Name	Type	Required	Description
error	{ code: string; message: string; message_i18n?: Partial<Record<Locale, string>>; details?: Record<string, unknown>; request_id?: string; }	yes	The error: code, message, message_i18n, details and request_id.

Interface EaiErrorInit

Fields given to the EaiError constructor.

Fields:

Name	Type	Required	Description
code	string	yes	Code of the control, 1 to 64 characters: a catalogue code such as EAI-GOV-01, or a custom one. Unique in the tenant.
message	string	yes	Status message (up to 2000 characters).
status	number	no	HTTP status of the response.
details	Record<string	no	Free attributes of the event, at most 16384 bytes once serialized.
requestId	string	no	Request id of the call.
messageI18n	Partial<Record<Locale	no	Message in en and fr.
retryAfterMs	number	no	Delay before a retry, in milliseconds.
cause	unknown	no	Original error, kept as cause.

Class EaiError

Base class of every SDK error: code, HTTP status, details with secrets masked, request id and localized messages.

Error

Attributes:

Name	Type	Required	Description
code	string	yes	Machine readable error code, for example policy_denied.
details	Record<string, unknown>	yes	Details sent by the server, secret looking keys replaced by ***.
messageI18n	Partial<Record<Locale, string>>	yes	Message of the server in en and fr when it sent them.
requestId	string | undefined	yes	Request id of the failed call, to quote to support.
retryAfterMs	number | undefined	yes	Delay asked by the Retry-After header, in milliseconds.
status	number | undefined	yes	HTTP status, undefined for a local or network error.

Constructor EaiError

new EaiError(init: EaiErrorInit)

Builds the error; the class name becomes name and the secret looking keys of details are masked.

Name	Type	Default	Required	Description
init	EaiErrorInit		yes	Code, message and optional status, details, request id, localized messages, retry delay and cause.

Class AuthError

Authentication or permission refused: codes unauthorized, unauthenticated, forbidden, invalid_credentials, or HTTP 401 and 403.

EaiError

Class EgressDeniedError

The egress guard refused an outbound call (403 egress_denied); reason is details.reason.

EaiError

EgressDeniedError.reason

reason(): string | undefined

Reason of the refusal, read from details.reason.

This element takes no parameter.

Returns: string \| undefined. The reason, or undefined when it is not a string.

Class PromptInjectionBlockedError

The prompt injection screen blocked the content (403 prompt_injection_blocked).

EaiError

Class PayloadTooLargeError

The request body exceeds the server limit (413 payload_too_large).

EaiError

Class NotFoundError

The resource does not exist (not_found or HTTP 404).

EaiError

Class PolicyDeniedError

A policy refused the action (policy_denied).

EaiError

PolicyDeniedError.decisionId

decisionId(): string | undefined

Id of the policy decision, read from details.decision_id.

This element takes no parameter.

Returns: string \| undefined. The decision id, or undefined when the server sent none.

PolicyDeniedError.reasons

reasons(): string[]

Reasons of the refusal, read from details.reasons.

This element takes no parameter.

Returns: string[]. The reasons as strings, an empty array when there are none.

Class QuotaExceededError

A quota or a budget is exhausted (quota_exceeded or budget_exceeded).

EaiError

Class EffortNotSupportedError

The model does not support the requested reasoning effort (effort_not_supported).

EaiError

Class ContextOverflowError

The context does not fit in the budget (context_overflow), raised by the server or by ContextBudget.

EaiError

Class ApprovalRequiredError

The action needs a human approval first (approval_required).

EaiError

ApprovalRequiredError.approvalId

approvalId(): string | undefined

Id of the approval to wait for, read from details.approval_id.

This element takes no parameter.

Returns: string \| undefined. The approval id, or undefined when the server sent none.

Class RateLimitError

Too many requests (rate_limited or HTTP 429); retryAfterMs gives the delay when the server sent one.

EaiError

Class ValidationError

One invalid field of a request.

EaiError

Class ConflictError

The request conflicts with the current state (conflict or HTTP 409).

EaiError

Class ServerError

Server failure (HTTP 500 or more) after the retries.

EaiError

Class NetworkError

The request did not get a response: network failure (network_error) or timeout (timeout).

EaiError

Class ContractValidationError

A document does not match its contract JSON Schema, or the contract is unknown.

EaiError

Class AgentLoopError

Error of the agent loop and of local tools: step limit, budget, abort, kill switch or invalid tool input.

EaiError

Class AuthzUnconfirmedError

An authorization answer without an explicit OPA or OpenFGA decision: the SDK never assumes an allow.

EaiError

Functions

redactSecrets

redactSecrets(value: unknown): unknown

Copy of a value with every secret looking key masked (recursive).

Name	Type	Default	Required	Description
value	unknown		yes	Value to copy: object, array or scalar.

Returns: unknown. The copy, keys such as api_key, token, password or authorization set to ***.

maskSecret

maskSecret(value: string | undefined): string | undefined

Masks a secret: at most 4 visible characters.

Name	Type	Default	Required	Description
value	string | undefined		yes	Secret to mask; an empty or missing value is returned as is.

Returns: string \| undefined. The first 4 characters and *** for a secret longer than 12 characters, else only ***.

errorFromResponse

errorFromResponse(status: number, body: unknown, locale: Locale, requestId?: string, retryAfterMs?: number): EaiError

Builds the typed error for an HTTP error response, using the server message in the client locale.

Name	Type	Default	Required	Description
status	number		yes	HTTP status of the response, used to choose the class when the code is unknown.
body	unknown		yes	Request body, serialized as JSON.
locale	Locale		yes	Language whose message is taken from message_i18n.
requestId	string		no	Request id of the response header, used when the body gives none.
retryAfterMs	number		no	Delay of the Retry-After header in milliseconds.

Returns: EaiError. The EaiError subclass of the error code or status; without an error envelope the code is http_<status>.