# Erreurs et limites de débit
Source: https://nordvec.com/fr/docs/guides/errors-and-rate-limits

L'enveloppe d'erreur unique que chaque requête échouée retourne, les en-têtes de limite de débit, et comment réessayer une écriture en toute sécurité.



Chaque point de terminaison échoue de la même manière, donc un client gère les erreurs, les limites de débit et les nouvelles tentatives une seule fois et réutilise ce code partout, y compris via [MCP](/docs/guides/mcp).

## L'enveloppe d'erreur [#lenveloppe-derreur]

Chaque réponse non-2xx est un objet JSON unique :

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` est l'erreur au niveau HTTP, par exemple `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` ou `TOO_MANY_REQUESTS`.
* `data.reason`, lorsqu'il est présent, est une raison plus précise lisible par machine, comme
  `auth.key_not_found` ou `rate_limit.exceeded`. Effectuez une branche sur celui-ci plutôt que sur
  `message`, qui est destiné aux utilisateurs et peut changer.
* `defined` est `true` lorsque l'opération répertorie cette erreur dans la
  [référence de l'API](/docs/api), et `false` pour les erreurs que toute requête peut rencontrer
  (authentification, limites de débit, une route inconnue).
* Un échec de validation répond `BAD_REQUEST` avec les problèmes dans
  `data.formErrors` et `data.fieldErrors`.

Chaque réponse comporte également un `X-Request-ID`. Citez-le lorsque vous contactez
le support, et nous pourrons retrouver cette requête exacte.

## Statuts courants [#statuts-courants]

| Statut | Code                    | Que faire                                                                           |
| ------ | ----------------------- | ----------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`           | Corrigez la requête ; `data.fieldErrors` nomme les champs                           |
| `401`  | `UNAUTHORIZED`          | Envoyez une clé ou une session valide                                               |
| `403`  | `FORBIDDEN`             | La clé ne dispose pas de l'étendue ou du rôle requis par l'opération                |
| `404`  | `NOT_FOUND`             | La ressource n'existe pas, ou vous n'êtes pas autorisé à la voir                    |
| `409`  | `CONFLICT`              | Une écriture en double est toujours en cours ; réessayez sous peu                   |
| `413`  | `PAYLOAD_TOO_LARGE`     | Le corps de la requête dépasse 1 Mo ; divisez un envoi en masse en lots plus petits |
| `422`  | `UNPROCESSABLE_CONTENT` | La requête est bien formée mais ne peut pas être appliquée                          |
| `429`  | `TOO_MANY_REQUESTS`     | Attendez `Retry-After`, puis réessayez                                              |

## Limites de débit [#limites-de-débit]

Chaque réponse indique la limite contre laquelle elle a été comptabilisée, sous deux formes :

* les en-têtes `X-RateLimit-*` ;
* les champs structurés IETF `RateLimit` (état en direct : `r` est le nombre de requêtes
  restantes, `t` le nombre de secondes avant la réinitialisation de la fenêtre) et `RateLimit-Policy`
  (le quota : `q` est la limite, `w` la fenêtre en secondes).

Une réponse `429` comporte également `Retry-After` en secondes et `data.retryAfterMs`. Attendez au moins
ce délai avant la requête suivante ; une nouvelle tentative plus tôt est comptabilisée et
refusée à nouveau.

## Réessayer les écritures en toute sécurité [#réessayer-les-écritures-en-toute-sécurité]

Une opération d'écriture qui répertorie un en-tête `Idempotency-Key` dans la
[référence de l'API](/docs/api) peut être réessayée sans effectuer le travail deux fois. Envoyez
une clé par écriture logique et répétez la même clé à chaque nouvelle tentative :

* la même clé avec le même corps dans les 24 heures rejoue la réponse stockée ;
* la même clé avec un corps différent est refusée avec `422` ;
* un doublon qui arrive alors que la première tentative est toujours en cours reçoit `409`.

Une opération sans cet en-tête n'est pas idempotente, donc ne la réessayez que lorsque vous
savez que la première tentative n'a pas abouti.