Retour aux docs APIOperational reference

Codes d’erreur et diagnostic

Les intégrations fiables ne s’arrêtent pas à un `200`. Cette page documente les erreurs attendues, les headers de débit et la manière de diagnostiquer chaque mutation avec `x-request-id`.

Auth

Les erreurs 401 viennent de la clé API, jamais du payload. Vérifiez d’abord la clé avant de rejouer.

Retry

Rejouez les mutations critiques avec la même Idempotency-Key seulement si le payload n’a pas changé.

Réponse réelle

Limiter les retries aveugles

HTTP/1.1 429 Too Many Requests
x-request-id: req_01HSQ3D6ZMBJH3J6BQ4X9G4P5R
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-04-09T15:31:00.000Z
Retry-After: 24
content-type: application/json

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for this API key.",
    "details": {
      "bucket": "minute",
      "retryAfterSeconds": 24
    }
  }
}

Réponses à traiter côté client

Le contrat d’erreur est stable. Les statuts HTTP et le code applicatif suffisent pour prendre la bonne décision de retry ou de correction.

400validation_errorLe payload est valide JSON mais ne respecte pas le contrat attendu.Corrigez les champs invalides. Réutilisez la même Idempotency-Key seulement si la mutation n’a pas été acceptée.
401unauthorizedLa clé API est absente, révoquée, suspendue ou invalide.Générez ou réactivez une clé API valide depuis le dashboard avant de rejouer.
409idempotency_conflictLa même Idempotency-Key a déjà été utilisée avec un payload différent.Créez une nouvelle clé d’idempotence pour cette nouvelle mutation.
429rate_limit_exceededLe débit autorisé pour la clé API a été dépassé sur la fenêtre courante.Lisez Retry-After et les headers X-RateLimit-* avant de rejouer.
500internal_errorUne erreur non prévue a interrompu le traitement avant réponse stable.Conservez x-request-id, puis rejouez les mutations critiques avec la même Idempotency-Key.

Headers à logger

x-request-idCorrélation support, logs et tracing côté client.
x-idempotency-status`stored` à la première exécution, `replayed` lors d’un replay.
X-RateLimit-LimitCapacité maximale de la fenêtre courante.
X-RateLimit-RemainingNombre de requêtes restantes avant `429`.
X-RateLimit-ResetDate ISO de réinitialisation de la fenêtre.
Retry-AfterPrésent sur `429` pour indiquer le temps d’attente conseillé.

Stratégie recommandée

  • Persistez `x-request-id` pour chaque mutation métier critique.
  • Traitez `409 idempotency_conflict` comme une erreur d’intégration, pas comme un retry automatique.
  • Sur `429`, utilisez `Retry-After` et évitez les boucles de retry instantané.
  • Sur `500`, rejouez seulement les mutations protégées par Idempotency-Key.
  • Exposez les erreurs métier à vos opérateurs avec le code et le request ID.