# Erreurs

https://gorally.games/developpeurs/erreurs

Quand une requête échoue, l’API répond avec un statut HTTP et un corps JSON de trois champs.

```json
{
  "error": "Cette clé est inconnue, révoquée ou expirée.",
  "code": "UNAUTHORIZED",
  "request_id": "9f2c41d7a3b54e0c"
}
```

- `error` : un message lisible, en français. Il peut changer : ne le compare jamais.
- `code` : un code stable. Branche ta logique dessus.
- `request_id` : l’identifiant de la requête.

## Les en-têtes à lire

- `X-Request-Id` : présent sur toute réponse, succès compris. Il vaut `request_id`. Recopie-le quand tu nous écris : c’est lui qui retrouve ta requête dans nos journaux. Tu peux aussi envoyer le tien, de 8 à 64 caractères parmi `A-Za-z0-9_.:-`.
- `Retry-After` : le nombre de secondes à attendre avant de réessayer. Il accompagne `RATE_LIMITED` et `LEAGUES_UNAVAILABLE`.

## Les codes

| Code | Statut | Cause | Que faire |
|---|---|---|---|
| `INVALID_INPUT` | `400` | Requête malformée : champ manquant, valeur hors bornes, corps illisible. | Corrige la requête d’après `error`, qui nomme le champ quand il le peut. |
| `UNAUTHORIZED` | `401` | Clé absente, mal formée, inconnue, révoquée ou expirée. | Vérifie l’en-tête `Authorization`. Si la clé est révoquée, émets-en une nouvelle. |
| `FORBIDDEN` | `403` | La clé n’a pas le scope de l’opération. | Émets une clé avec le bon scope. |
| `ENTITLEMENT_DENIED` | `403` | L’abonnement de l’organisation ne permet pas cet accès. | Vérifie le forfait Ligues de l’organisation. |
| `NOT_FOUND` | `404` | L’élément n’existe pas dans l’organisation de la clé, ou la route n’existe pas. | Vérifie l’identifiant et le chemin. |
| `CONFLICT` | `409` | La révision envoyée est périmée, ou l’élément n’admet plus cette commande. | Relis l’élément, puis décide. Ne réessaie pas à l’aveugle. |
| `IDEMPOTENCY_KEY_REUSED` | `409` | Cette `Idempotency-Key` a déjà servi avec un corps différent. | Prends une clé neuve pour une nouvelle requête. |
| `IDEMPOTENT_REQUEST_IN_FLIGHT` | `409` | Une requête avec cette `Idempotency-Key` est encore en cours. | Réessaie dans un instant, avec la même clé. |
| `IDEMPOTENCY_OUTCOME_UNKNOWN` | `409` | Une requête avec cette `Idempotency-Key` s’est interrompue sans issue connue. | Relis l’élément pour savoir s’il a été créé, puis reprends avec une clé neuve. |
| `ROTATION_EN_COURS` | `409` | Une rotation du secret de ce point de livraison est déjà en grâce. | Attends la fin de la grâce, ou fais une rotation avec coupure immédiate. |
| `BODY_TOO_LARGE` | `413` | Le corps dépasse 16 Kio. | Réduis le corps. L’API ne transporte aucun fichier. |
| `RATE_LIMITED` | `429` | Trop de requêtes, depuis ton adresse ou avec ta clé. | Attends `Retry-After` secondes, puis reprends avec un recul exponentiel bruité. |
| `LEAGUES_UNAVAILABLE` | `503` | Panne passagère, ou requête plus longue que 10 secondes. | Attends `Retry-After` secondes. Après une écriture, vérifie son état avant de la répéter. |
| `ENTITLEMENT_UNAVAILABLE` | `503` | Le droit de l’organisation ne peut pas être vérifié pour l’instant. | Réessaie plus tard, avec un recul. |
| `HOLDER_UNINITIALIZED` | `503` | L’organisation n’a pas encore désigné le détenteur de son abonnement. | Demande à une personne qui gère l’organisation de le désigner. |
| `WEBHOOK_VAULT_UNAVAILABLE` | `503` | Les webhooks ne sont pas configurés sur ce serveur. | Écris-nous : ce n’est pas un réglage de ton organisation. |

`ROTATION_EN_COURS` et `WEBHOOK_VAULT_UNAVAILABLE` viennent de la gestion des webhooks, dans l’écran Intégrations. Tu les croises rarement par l’API.

## Réessayer ou pas

- `4xx` : la requête est en cause. Corrige-la avant de la renvoyer, sauf pour `429` et `IDEMPOTENT_REQUEST_IN_FLIGHT`.
- `5xx` : Rally est en cause. Réessaie avec un recul exponentiel bruité.
- Sur un `POST`, envoie une `Idempotency-Key`. Un nouvel envoi rejoue alors la réponse d’origine pendant 24 heures, sans doublon.

Si tu reçois un `code` que ton logiciel ne connaît pas, traite-le d’après le statut HTTP.