Codes d'erreur
Une seule enveloppe pour tous les échecs :
{ "error": { "code": "invalid_request", "message": "…" } }
| HTTP | code |
Quand | Que faire |
|---|---|---|---|
| 401 | missing_api_key |
Pas d'en-tête Authorization: Bearer sk_… ni X-API-Key |
Ajoutez la clé |
| 401 | invalid_api_key |
Clé révoquée, inconnue ou compte inactif | Vérifiez la clé et le statut du compte |
| 403 | insufficient_scope |
La clé n'a pas ce droit (par exemple verser) | Émettez une clé avec le bon périmètre |
| 403 | client_inactive |
Le compte n'est pas validé, ou il est suspendu | Terminez le dossier KYB |
| 403 | not_live |
Compte pas encore ouvert au mode réel | Utilisez une clé sk_test_ en attendant |
| 404 | not_found |
Ressource inexistante — ou pas à vous | Vérifiez l'identifiant |
| 409 | already_exists |
Doublon (référence déjà utilisée) | Relisez la ressource existante |
| 409 | precondition_failed |
L'état ne permet pas l'opération | Consultez la ressource, corrigez l'enchaînement |
| 409 | concurrent_request |
Même Idempotency-Key, charge utile différente |
N'en réutilisez pas une pour deux opérations |
| 422 | invalid_request |
Corps invalide (champ, montant, actif) | Le message nomme le champ fautif |
| 422 | insufficient_funds |
Solde insuffisant pour ce versement | Consultez GET /v1/balances |
| 429 | — | 300 requêtes/minute dépassées | Honorez l'en-tête Retry-After |
| 502 | upstream_error |
Une dépendance a échoué | Rejouez avec le même Idempotency-Key |
| 503 | temporarily_unavailable |
Indisponibilité passagère | Rejouez avec backoff |
Rejouer sans risque
Les 502 et 503 se rejouent toujours avec le même Idempotency-Key : si la première requête
avait abouti côté serveur, vous récupérez son résultat au lieu de créer un doublon.
Un
502ne veut pas dire que rien ne s'est passé. Il dit qu'une dépendance n'a pas répondu, pas que l'opération n'existe pas. C'est exactement la situation pour laquelle l'idempotence existe : rejouez, ne recréez pas.
not_found sur une ressource qui existe
L'API répond 404 aussi quand la ressource appartient à un autre marchand : ne déduisez jamais
l'existence d'une ressource d'un 404.
Un corps refusé n'est pas un champ ignoré
Un champ inconnu dans un corps JSON est ignoré silencieusement, pas rejeté. Une faute de frappe
sur un nom de champ optionnel ne produit donc aucune erreur : elle produit une opération créée sans
ce que vous croyiez avoir envoyé. Relisez les noms dans la référence plutôt
que de vous fier à l'absence de 422.