Codes d'erreur
Format des erreurs et codes les plus fréquents.
En cas d'erreur, l'API renvoie un statut HTTP et un corps JSON structuré.
Format
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request payload or query parameters are invalid.",
"requestId": "req_01HXFREEGATE"
}
}code— code d'erreur stable. Traitez-le dans votre code.message— texte lisible. Il peut changer. Ne le parsez pas.requestId— identifiant de la requête. Donnez-le au support.
Statuts HTTP
| Statut | Signification |
|---|---|
401 | Clé API manquante ou invalide. |
403 | Scope manquant sur la clé. |
404 | Ressource introuvable (par ex. transaction inconnue). |
409 | Conflit d'état, de solde ou de référence marchand. |
422 | Payload ou paramètres invalides. |
500 | Erreur interne. |
Codes fréquents
| Code | Contexte |
|---|---|
AUTH_API_KEY_MISSING | Clé API absente ou invalide (401). |
AUTH_SCOPE_MISSING | La clé n'a pas le scope requis (403). |
VALIDATION_ERROR | Requête invalide (422). |
PAYMENT_TRANSACTION_NOT_FOUND | Transaction introuvable (404). |
INSUFFICIENT_FUNDS | Solde disponible insuffisant (409). |
PAYMENT_ROUTE_UNAVAILABLE | Aucune route de paiement pour cette opération (409). |
IDEMPOTENCY_CONFLICT | Même merchantReference réutilisé avec une requête différente (409). |
IDEMPOTENCY_REPLAY_UNAVAILABLE | Requête en cours de traitement, rejeu impossible (409). |
REFUND_ORIGINAL_TRANSACTION_NOT_REFUNDABLE | La transaction d'origine n'est pas remboursable (409). |
INTERNAL_ERROR | Erreur interne (500). |
Idempotence et conflits
Le merchantReference est votre clé d'idempotence.
- Même référence, même requête : vous rejouez la réponse d'origine.
- Même référence, requête différente : vous recevez
IDEMPOTENCY_CONFLICT.
La liste complète des erreurs par endpoint, avec exemples, est dans la référence API.