# Erreurs et limites de débit

Les erreurs de l’API KolWrite utilisent des réponses JSON comportant un `code`
stable chaque fois que le client peut intervenir.

```json
{
  "detail": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'jobs:write' scope",
    "required_scope": "jobs:write"
  }
}
```

## Statuts courants

| Statut | Signification |
|---|---|
| `400` | Entrée non valide ou combinaison d’options non prise en charge |
| `401` | Token manquant, non valide, expiré ou révoqué |
| `403` | Token valide, mais dépourvu du scope ou de l’accès à la route requis |
| `404` | Ressource absente ou non visible par le propriétaire du token |
| `409` | Conflit, généralement lié à l’idempotence ou à une transition d’état |
| `422` | Le corps de la requête est un JSON valide, mais échoue à la validation |
| `429` | Limite de débit atteinte ou capacité de réservation de crédits sous tension |
| `5xx` | Erreur temporaire du service KolWrite |

## Recommandations de nouvelle tentative

Réessayez après les réponses `429`, `502`, `503` et `504` en appliquant un délai
exponentiel assorti d’une gigue aléatoire. Utilisez `Idempotency-Key` lors de la
création d’un job afin que les nouvelles tentatives réseau ne créent jamais de
doublons. Ne réessayez pas après une réponse `401` ou `403`, ni après une erreur
de validation, tant que le token ou la requête n’a pas été corrigé.