> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retriever.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Erreurs

> Format standard des erreurs de l'API Retriever, codes stables par statut HTTP et actions à mener.

## Format

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

```json theme={null}
{
  "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 :

```json theme={null}
{
  "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` :

```json theme={null}
{
  "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](/concepts/rate-limits). |
| `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` :

```json theme={null}
{ "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](/recipes/robust-integrations).