Reference
Errors
Toutes les erreurs partagent la même enveloppe et un code normalisé. Aucun détail interne du prestataire n'est exposé — n'écrivez jamais de logique sur un message brut.
Enveloppe
Le champ code est stable et fait partie du contrat d'API. Le champ message est destiné aux humains et peut changer. Conservez request_id : c'est ce que nous demandons en support.
422 Unprocessable Entity
{
"error": {
"code": "validation_error",
"message": "amount must be a positive integer in minor units",
"request_id": "req_01HZY8..."
}
}Codes
| Champ | Type | Description |
|---|---|---|
| invalid_request | 400 | Requête malformée : JSON invalide ou champ inattendu. |
| authentication_error | 401 | Clé API absente, révoquée ou invalide. |
| authorization_error | 403 | La clé n'a pas accès à cette ressource. |
| payment_failed | 402 | Le paiement a été refusé. Ne pas réessayer à l'identique. |
| payout_failed | 402 | Le payout a été refusé par la destination. |
| resource_not_found | 404 | L'objet demandé n'existe pas pour cette société. |
| payment_cancelled | 409 | Transition impossible : le paiement est déjà annulé. |
| payout_reversed | 409 | Transition impossible : le payout a été renvoyé. |
| idempotency_conflict | 409 | Idempotency-Key réutilisée avec un payload différent. |
| validation_error | 422 | Paramètre manquant ou invalide. |
| rate_limit | 429 | Trop de requêtes. Réessayer avec un backoff exponentiel. |
| internal_error | 500 | Erreur interne. Réessayer avec un backoff. |
| provider_error | 502 | Le rail de paiement a répondu en erreur. Réessayable. |
| provider_timeout | 504 | Délai dépassé côté rail. Réessayer avec la même Idempotency-Key. |
Que réessayer
Réessayables avec la même Idempotency-Key : rate_limit, internal_error, provider_error, provider_timeout. La clé d'idempotence garantit qu'un objet déjà créé ne sera pas dupliqué.
Non réessayables tels quels : validation_error, invalid_request, authentication_error, authorization_error, payment_failed, payout_failed. Corrigez la requête ou la situation avant tout nouvel appel.
Sur provider_timeout, l'opération a pu aboutir côté rail. Rejouez le même appel avec la même clé d'idempotence, ou relisez l'objet, plutôt que d'en créer un nouveau.
Environnement Sandbox
Les erreurs ci-dessus sont reproduites à l'identique dans l'environnement de test, pour vous permettre de valider chaque branche de votre code.