Erreurs, limites et reprises.

Les erreurs utilisent une structure commune. Votre intégration doit distinguer les corrections fonctionnelles des incidents temporaires.

Décider quand réessayer

Statut	Signification	Action
`400`	Paramètre ou corps invalide	Corriger la requête, ne pas relancer automatiquement
`401`	Jeton absent ou expiré	Renouveler le jeton puis relancer une fois
`403`	Scope manquant	Demander une permission, ne pas relancer
`409`	Conflit métier ou d’idempotence	Inspecter le code d’erreur avant toute nouvelle tentative
`429`	Trop de requêtes	Attendre puis reprendre progressivement
`503`	Service temporairement indisponible	Réessayer avec délai exponentiel

Format d’une erreur

Réponse 403json

{
  "statusCode": 403,
  "code": "MISSING_SCOPE",
  "error": "Forbidden",
  "message": "Permission insuffisante",
  "missingScopes": ["stock:read"]
}

Idempotence du débit d’une carte cadeau

PUT /v1/gift-cards/{giftCardId} demande un en-tête Idempotency-Key. Conservez la même clé uniquement pour rejouer exactement la même intention.

Clé de reprisehttp

Idempotency-Key: gift-card-debit-2026-000142

Pendant la fenêtre de rétention configurée, 24 heures par défaut, la même clé et le même corps rejouent la première réponse. La même clé avec un corps différent retourne un conflit 409.

Journalisation utile

Conservez l’opération appelée, le statut HTTP, le code d’erreur, votre référence externe et la clé d’idempotence. Ne journalisez jamais les mots de passe, jetons ou codes complets de cartes cadeaux.

Précédent← Authentification RéférenceConsulter les opérations →