errors.ts
Source : sdks/typescript/packages/sdk/src/errors.ts. Retour à l'index de la référence du SDK TypeScript.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Interface ErrorEnvelope
Corps JSON d'erreur de l'API : code, message, messages localisés, détails et identifiant de requête sous error.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
error | { code: string; message: string; message_i18n?: Partial<Record<Locale, string>>; details?: Record<string, unknown>; request_id?: string; } | oui | L'erreur : code, message, message_i18n, details et request_id. |
Interface EaiErrorInit
Champs transmis au constructeur d'EaiError.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
code | string | oui | Code du contrôle, 1 à 64 caractères : un code du catalogue comme EAI-GOV-01, ou un code personnalisé. Unique dans le tenant. |
message | string | oui | Message d'état (2000 caractères au plus). |
status | number | non | Statut HTTP de la réponse. |
details | Record<string | non | Attributs libres de l'événement, 16384 octets au plus une fois sérialisés. |
requestId | string | non | Identifiant de la requête. |
messageI18n | Partial<Record<Locale | non | Message en en et fr. |
retryAfterMs | number | non | Délai avant une nouvelle tentative, en millisecondes. |
cause | unknown | non | Erreur d'origine, conservée en cause. |
Classe EaiError
Classe de base de toutes les erreurs du SDK : code, statut HTTP, détails aux secrets masqués, identifiant de requête et messages localisés.
Error
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
code | string | oui | Code d'erreur lisible par une machine, par exemple policy_denied. |
details | Record<string, unknown> | oui | Détails envoyés par le serveur, les clés qui ressemblent à des secrets étant remplacées par ***. |
messageI18n | Partial<Record<Locale, string>> | oui | Message du serveur en en et fr quand il les a envoyés. |
requestId | string | undefined | oui | Identifiant de la requête en échec, à communiquer au support. |
retryAfterMs | number | undefined | oui | Délai demandé par l'en-tête Retry-After, en millisecondes. |
status | number | undefined | oui | Statut HTTP, undefined pour une erreur locale ou réseau. |
Constructeur EaiError
new EaiError(init: EaiErrorInit)
Construit l'erreur ; le nom de la classe devient name et les clés de details qui ressemblent à des secrets sont masquées.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
init | EaiErrorInit | oui | Code, message et, en option, statut, détails, identifiant de requête, messages localisés, délai avant nouvel essai et cause. |
Classe AuthError
Authentification ou permission refusée : codes unauthorized, unauthenticated, forbidden, invalid_credentials, ou HTTP 401 et 403.
EaiError
Classe EgressDeniedError
Le garde de sortie a refusé un appel sortant (403 egress_denied) ; reason vaut details.reason.
EaiError
EgressDeniedError.reason
reason(): string | undefined
Motif du refus, lu dans details.reason.
Cet élément ne prend aucun paramètre.
Retour : string \| undefined. Le motif, ou undefined quand ce n'est pas une chaîne.
Classe PromptInjectionBlockedError
Le filtre d'injection de prompt a bloqué le contenu (403 prompt_injection_blocked).
EaiError
Classe PayloadTooLargeError
Le corps de la requête dépasse la limite du serveur (413 payload_too_large).
EaiError
Classe NotFoundError
La ressource n'existe pas (not_found ou HTTP 404).
EaiError
Classe PolicyDeniedError
Une politique a refusé l'action (policy_denied).
EaiError
PolicyDeniedError.decisionId
decisionId(): string | undefined
Identifiant de la décision de politique, lu dans details.decision_id.
Cet élément ne prend aucun paramètre.
Retour : string \| undefined. L'identifiant de la décision, ou undefined quand le serveur n'en a pas envoyé.
PolicyDeniedError.reasons
reasons(): string[]
Motifs du refus, lus dans details.reasons.
Cet élément ne prend aucun paramètre.
Retour : string[]. Les motifs sous forme de chaînes, un tableau vide quand il n'y en a pas.
Classe QuotaExceededError
Un quota ou un budget est épuisé (quota_exceeded ou budget_exceeded).
EaiError
Classe EffortNotSupportedError
Le modèle ne prend pas en charge l'effort de raisonnement demandé (effort_not_supported).
EaiError
Classe ContextOverflowError
Le contexte ne tient pas dans le budget (context_overflow), levée par le serveur ou par ContextBudget.
EaiError
Classe ApprovalRequiredError
L'action exige d'abord une approbation humaine (approval_required).
EaiError
ApprovalRequiredError.approvalId
approvalId(): string | undefined
Identifiant de l'approbation à attendre, lu dans details.approval_id.
Cet élément ne prend aucun paramètre.
Retour : string \| undefined. L'identifiant de l'approbation, ou undefined quand le serveur n'en a pas envoyé.
Classe RateLimitError
Trop de requêtes (rate_limited ou HTTP 429) ; retryAfterMs donne le délai quand le serveur en a envoyé un.
EaiError
Classe ValidationError
Un champ invalide d'une requête.
EaiError
Classe ConflictError
La requête entre en conflit avec l'état courant (conflict ou HTTP 409).
EaiError
Classe ServerError
Défaillance du serveur (HTTP 500 ou plus) après les nouvelles tentatives.
EaiError
Classe NetworkError
La requête n'a pas obtenu de réponse : échec réseau (network_error) ou expiration (timeout).
EaiError
Classe ContractValidationError
Un document ne respecte pas le JSON Schema de son contrat, ou le contrat est inconnu.
EaiError
Classe AgentLoopError
Erreur de la boucle d'agent et des outils locaux : limite d'étapes, budget, annulation, arrêt d'urgence ou entrée d'outil invalide.
EaiError
Classe AuthzUnconfirmedError
Une réponse d'autorisation sans décision OPA ou OpenFGA explicite : le SDK ne suppose jamais une autorisation.
EaiError
Fonctions
redactSecrets
redactSecrets(value: unknown): unknown
Copie d'une valeur dont chaque clé ressemblant à un secret est masquée (récursif).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
value | unknown | oui | Valeur à copier : objet, tableau ou scalaire. |
Retour : unknown. La copie, avec les clés comme api_key, token, password ou authorization remplacées par ***.
maskSecret
maskSecret(value: string | undefined): string | undefined
Masque un secret : au plus 4 caractères visibles.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
value | string | undefined | oui | Secret à masquer ; une valeur vide ou absente est renvoyée telle quelle. |
Retour : string \| undefined. Les 4 premiers caractères suivis de *** pour un secret de plus de 12 caractères, sinon seulement ***.
errorFromResponse
errorFromResponse(status: number, body: unknown, locale: Locale, requestId?: string, retryAfterMs?: number): EaiError
Construit l'erreur typée d'une réponse HTTP en erreur, avec le message du serveur dans la langue du client.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
status | number | oui | Statut HTTP de la réponse, utilisé pour choisir la classe quand le code est inconnu. | |
body | unknown | oui | Corps de la requête, sérialisé en JSON. | |
locale | Locale | oui | Langue dont le message est pris dans message_i18n. | |
requestId | string | non | Identifiant de requête de l'en-tête de réponse, utilisé quand le corps n'en donne pas. | |
retryAfterMs | number | non | Délai de l'en-tête Retry-After en millisecondes. |
Retour : EaiError. La sous-classe d'EaiError du code ou du statut ; sans enveloppe d'erreur, le code vaut http_<status>.