> For the complete documentation index, see [llms.txt](https://guides.ia.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.ia.numerique.gouv.fr/albert-api/ressources/errors.md).

# Codes d'erreur

Albert API s’appuie sur FastAPI / Pydantic : les erreurs métier suivent en général le schéma **`HTTPExceptionModel`**, tandis que les requêtes mal formées peuvent produire une **`HTTPValidationError`**.

## Schémas `HTTPExceptionModel` (deux variantes)

La spec OpenAPI enregistre **deux** modèles homonymes pour les réponses d’exception HTTP :

### Variante « infrastructure » (`api.infrastructure.fastapi.documentation.HTTPExceptionModel`)

Utilisée par exemple pour certaines réponses **401** :

* **`status_code`** — entier HTTP ;
* **`detail`** — **chaîne** décrivant l’erreur (ex. clé invalide) ;
* **`headers`** — tableau associatif string → string optionnel.

Les champs **`status_code`** et **`detail`** sont **requis**. Le champ **`headers`** est optionnel et peut être absent ou `null`.

### Variante « exceptions API » (`api.schemas.exception.HTTPExceptionModel`)

Utilisée notamment pour les réponses **503** de type *« Model is too busy »* sur `POST /v1/chat/completions` et `POST /v1/ocr` :

* **`status_code`** — entier entre **100 et 599** (contrainte min/max dans le schéma) ;
* **`detail`** — **contenu quelconque** sérialisable JSON (pas limité à une chaîne) ;
* **`headers`** — map optionnelle ; dans ce schéma la clé **`headers`** doit être **présente** sur l’objet (champ requis au sens JSON Schema) mais sa valeur peut être **`null`** ou un dictionnaire de paires chaîne → chaîne.

En pratique, commencez par lire **`status_code`** et sérialisez **`detail`** en texte pour les logs sans supposer uniquement une chaîne plate.

## Erreurs de validation — `HTTPValidationError`

Corps typique :

* **`detail`** — liste d’objets **`ValidationError`** avec :
  * **`loc`** — chemin du champ fautif (chaînes et entiers mélangés) ;
  * **`msg`** — message lisible ;
  * **`type`** — code d’erreur Pydantic / JSON Schema.

Réponse HTTP associée : **422 Unprocessable Entity**.

## Table des statuts HTTP courants

| Code    | Signification       | Contexte                                                                                   |
| ------- | ------------------- | ------------------------------------------------------------------------------------------ |
| **200** | OK                  | Lecture réussie (liste, détail, streaming entamé correctement).                            |
| **201** | Created             | Ressource créée (ex. certaines collections).                                               |
| **204** | No Content          | Suppression ou action sans corps de réponse.                                               |
| **401** | Unauthorized        | Schéma d’authentification invalide ou jeton refusé.                                        |
| **403** | Forbidden           | Accès refusé au routeur ou à l’opération (permissions, limite à zéro, ou règle de droits). |
| **404** | Not Found           | Ressource absente ou identifiant inconnu (y compris modèle indisponible pour le compte).   |
| **422** | Validation Error    | Corps ou paramètres hors schéma (`HTTPValidationError`).                                   |
| **429** | Too Many Requests   | Dépassement de quota / rate limiting (requêtes ou tokens selon configuration).             |
| **503** | Service Unavailable | Saturation modèle : message *« Model is too busy, please try again later. »*               |

## Cas particulier : 429 (limites / quotas)

En cas de **429**, réduisez le débit, mettez en file d’attente côté client, et relancez avec un délai croissant. Si l’API renvoie un **`Retry-After`**, respectez-le.

## Cas particulier : 503 « Model is too busy »

Lorsque le moteur d’inférence est saturé, les endpoints concernés peuvent répondre **503** avec le schéma `HTTPExceptionModel` « exceptions API ». Recommandations :

1. **Retry avec backoff exponentiel** — espacer les nouvelles tentatives (centaines de ms → secondes) et borner le nombre total d’essais.
2. **Éviter le thundering herd** — jitter aléatoire sur les clients multiples partageant le même compte.
3. **Idempotence** — pour les opérations non naturellement idempotentes, gardez un identifiant métier côté client avant de relancer.
4. **Streaming** — si vous ouvrez déjà un flux, anticipez une coupure réseau ou une erreur mid-stream identique à traiter comme échec retriable.

Pour une cartographie complète des réponses par route : la [liste des endpoints GitBook](https://doc.incubateur.net/alliance/albert-api/api-reference/liste-des-endpoint)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guides.ia.numerique.gouv.fr/albert-api/ressources/errors.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.