Erreurs API

Réponses 4xx/5xx, rate limits, idempotence et diagnostic.

Erreurs

HTTP	Code	Signification	Action
400	validation_error	Le 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.
401	unauthorized	La 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.
403	api_key_scope_required	La clé API est valide mais ne possède pas le droit requis pour cet endpoint.	Utilisez une clé avec le droit requis ou générez un profil plus adapté depuis le dashboard.
409	idempotency_conflict	La 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.
409	api_key_active_limit_reached	L’organisation possède déjà cinq clés API actives.	Révoquez une ancienne clé avant d’en créer une nouvelle.
429	rate_limit_exceeded	Le débit autorisé pour ce endpoint, cette organisation et cette clé API a été dépassé sur la fenêtre courante.	Lisez Retry-After et les headers X-RateLimit-* avant de rejouer.
500	internal_error	Une erreur non prévue a interrompu le traitement avant réponse stable.	Conservez x-request-id. Rejouer avec la même Idempotency-Key renvoie la même réponse : vérifiez l’état du message avant tout nouvel envoi.

En-têtes

Header	Rôle
x-request-id	Corrélation support, logs et tracing côté client.
X-RateLimit-Limit	Capacité maximale de la fenêtre courante pour le bucket du endpoint appelé.
X-RateLimit-Remaining	Nombre de requêtes restantes avant `429`.
X-RateLimit-Reset	Date ISO de réinitialisation de la fenêtre.
Retry-After	Présent sur `429` pour indiquer le temps d’attente conseillé.

Réponse 429

http

HTTP/1.1 429 Too Many Requests
x-request-id: req_01HSQ3D6ZMBJH3J6BQ4X9G4P5R
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-18T15: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
    }
  }
}

Diagnostic

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

← Revendeurs Exemples →