Erreurs - Retriever API

Format

Toutes les erreurs HTTP de l’API ont cette enveloppe :

{
  "error": {
    "code": "not_authenticated",
    "message": "A valid API key is required."
  }
}

Champ	Usage
`code`	Stable. Branchez votre logique dessus.
`message`	Pour les humains. Peut changer. En anglais.
`details`	Optionnel. Sur `invalid_request` et `validation_error` : liste des champs invalides.

Erreurs de validation

Sur /v1/runs, /v1/tables, /v1/workspaces et /v1/exclusions, un corps ou une query invalide répond 400 invalid_request. message nomme chaque champ en faute. details donne la même liste sous forme structurée :

{
  "error": {
    "code": "invalid_request",
    "message": "prompt: prompt must not be blank; columns[0].key: Too small: expected string to have >=1 characters",
    "details": [
      { "path": "prompt", "message": "prompt must not be blank" },
      { "path": "columns[0].key", "message": "Too small: expected string to have >=1 characters" }
    ]
  }
}

Un champ inconnu a un path vide et le message Unrecognized key: "…".
Un corps JSON illisible répond Request body must be valid JSON.

Sur /v1/go/* et /services, un corps invalide répond 400 validation_error avec details :

{
  "error": {
    "code": "validation_error",
    "message": "query is required",
    "details": [{ "path": ["query"], "message": "query is required" }]
  }
}

Statuts et codes

HTTP	`code`	Cause	Que faire
`400`	`invalid_request`	JSON illisible, champ ou paramètre de query inconnu, type incorrect, `limit` hors de 1–1000, `Idempotency-Key` vide, contrat `output` invalide.	Corrigez les champs nommés dans `message` et `details`.
`400`	`validation_error`	Entrée refusée par Go ou Services.	Corrigez les champs listés dans `details`.
`400`	`invalid_cursor`	Le curseur vient d’une autre table ou d’un autre run.	Relancez la lecture sans `cursor`.
`400`	`workspace_mismatch`	`conversation_id` n’appartient pas au `workspace_id` fourni.	Envoyez un seul des deux, ou la bonne paire.
`401`	`not_authenticated`	En-tête `Authorization` absent, mal formé, ou clé révoquée.	Vérifiez le format `Bearer ret_live_…`. Créez une nouvelle clé si besoin.
`402`	`insufficient_credits`, `usage_limit`	Solde insuffisant (Go, Services).	Consultez `GET /credits`, rechargez, puis réessayez.
`404`	`run_not_found`, `table_not_found`, `workspace_not_found`, `conversation_not_found`, `output_not_found`, `export_not_found`, `not_found`	Ressource inconnue, archivée, ou d’une autre organisation.	Vérifiez l’identifiant et la clé utilisée.
`409`	`idempotency_conflict`	Même `Idempotency-Key`, corps différent.	Bug client : générez une nouvelle clé pour une nouvelle demande.
`409`	`conversation_busy`	Un run est déjà actif dans cette conversation (API ou chat).	Attendez la fin du run actif, ou annulez-le.
`415`	`invalid_request`	`Content-Type` absent ou différent de `application/json`.	Ajoutez `Content-Type: application/json`.
`429`	`rate_limited`	Budget de requêtes dépassé.	Attendez `Retry-After` secondes. Voir Limites de débit.
`500`	`internal_error`	Erreur serveur inattendue.	Réessayez avec backoff : `GET`, ou `POST` avec `Idempotency-Key`.
`502`	`provider_error`, `upstream_error`, `agent_error` (Go), `capability_error` (Services)	Un fournisseur externe a échoué.	Réessayez avec backoff. Un `POST` Go ou Services rejoué est refacturé.
`503`	`runs_unavailable`	Stockage des runs indisponible (`/v1/runs`, `/v1/tables`).	Réessayez plus tard.

Échec d’un job et erreur HTTP

Un run ou un job Go qui échoue reste une ressource lisible en 200. Lisez status et error :

{ "id": "run_001", "status": "failed", "error": { "code": "agent_execution_failed", "message": "…" } }

Codes possibles de run.error.code : agent_execution_failed, run_lease_lost, run_access_revoked, agent_ suivi d’un statut. Pour les codes internes, message peut être identique à code. Pour savoir quelles erreurs réessayer, voir Rendre vos intégrations robustes.