Ne jamais reessayer
invalid_request, invalid_amount, unknown_asset_or_rail, asset_not_offered, unauthorized. La requete est fautive : la reessayer a l’identique produira le meme resultat. Corrigez, ou affichez le motif.
Developpeurs
Catalogue des erreurs
Chaque erreur porte un code stable, lisible par une machine, et un statut HTTP coherent. Le code est ce sur quoi votre integration doit brancher sa logique : le texte peut evoluer, le code non.
Forme d’une erreur
La forme actuelle est volontairement minimale. Elle est stable, et c’est ce qui compte : un code, et rien qui laisse fuiter un detail interne.
{ "error": "rate_stale" }{
"error": "rail_not_open",
"reason": {
"fr": "La retenue TDS de 1 % et l’enregistrement FIU-IND exigent une entite locale…",
"en": "The 1% TDS withholding and FIU-IND registration require a local entity…"
}
}Certaines erreurs portent un objet reason bilingue, destine a etre affiche tel quel a l’utilisateur. C’est le cas d’un rail ferme : le motif explique une contrainte reglementaire nommee, pas une panne, et l’afficher evite une demande au support. L’API versionnee ajoutera un identifiant de requete a cette enveloppe, pour que vous puissiez nous citer une ligne precise de nos journaux.
Codes en vigueur
Ces codes sont rendus aujourd’hui par l’endpoint de cotation.
| code | HTTP | Ce que cela signifie | Conduite a tenir |
|---|---|---|---|
invalid_request | 400 | Le corps de la requete ne passe pas la validation de schema : champ manquant, type incorrect, valeur hors des bornes autorisees. | Verifiez que amount est bien une chaine et non un nombre, et que direction vaut exactement « sell » ou « receive ». |
invalid_amount | 400 | Le montant n’est pas analysable, ou porte plus de decimales que l’actif ou la devise n’en accepte. | Tronquez a la precision de l’unite : 6 decimales pour USDT, 8 pour BTC, 2 pour l’euro, 0 pour le franc CFA. |
unknown_asset_or_rail | 404 | L’identifiant d’actif ou de rail n’existe pas dans le catalogue. | Les identifiants sont stables et ne sont jamais reattribues. Rechargez le catalogue plutot que de les deviner. |
rail_not_open | 409 | Le rail existe mais n’est pas ouvert. La reponse porte le motif exact, dans les deux langues. | Affichez le motif tel quel : il explique une contrainte reglementaire, pas une panne. Proposez un rail ouvert du meme pays. |
asset_not_offered | 409 | L’actif est au catalogue mais n’est pas propose — cas des actifs a anonymat renforce. | Ne le proposez pas dans votre selecteur. Le catalogue le rend avec son motif pour que vous puissiez l’expliquer. |
rate_stale | 503 | Le dernier prix connu depasse l’age maximum tolere. Le moteur refuse de coter plutot que de servir un prix perime comme un prix ferme. | Reessayez apres quelques secondes. Ne mettez pas en cache la derniere cotation reussie pour combler le trou : ce serait exactement l’erreur que ce code evite. |
rate_unavailable | 503 | Aucun prix n’est disponible pour cette paire actif / devise. | Desactivez la paire dans votre interface plutot que d’afficher une estimation. Une estimation affichee devient une attente. |
quote_failed | 500 | Erreur inattendue pendant le calcul. Aucune cotation n’est rendue. | Reessayez une fois ; si l’erreur persiste, ecrivez-nous avec l’horodatage exact de l’appel. |
Codes du contrat publie
Ces codes accompagnent les endpoints qui ne sont pas encore ouverts. Ils sont publies pour que votre gestion d’erreurs soit ecrite une seule fois.
| code | HTTP | Ce que cela signifie | Conduite a tenir |
|---|---|---|---|
unauthorized | 401 | Cle absente, revoquee, ou utilisee sur le mauvais environnement. | Une cle sk_test_ ne fonctionne pas en production, et l’inverse non plus : c’est volontaire. |
idempotency_conflict | 409 | La meme cle d’idempotence a deja ete utilisee avec un corps de requete different. | Une cle appartient a une intention. Si le contenu change, la cle change ; sinon on ne saurait plus laquelle des deux commandes rejouer. |
quote_expired | 409 | La cotation a depasse sa fenetre de verrouillage. | Recotez et faites accepter le nouveau montant. Nous ne reprisons jamais silencieusement en defaveur du client. |
beneficiary_rejected | 422 | Les coordonnees du beneficiaire echouent a la validation du rail : cle de controle invalide, format non conforme, ou nom ne correspondant pas a l’identite verifiee. | La reponse designe le champ fautif. Le nom du beneficiaire doit etre celui de l’identite verifiee : aucun payout vers un tiers n’est possible. |
country_not_served | 451 | Le pays de destination n’est pas desservi : sanctions, mesures restrictives, ou absence d’un cadre local. | Le code 451 est choisi expres plutot qu’un 404 : quand on refuse, on dit que c’est un refus et pourquoi. |
rate_limited | 429 | Trop d’appels sur la fenetre glissante. | Respectez l’en-tete Retry-After. Les cotations sont peu couteuses a mettre en file, pas a marteler. |
not_found | 404 | La ressource n’existe pas, ou n’appartient pas a votre cle. | Les deux cas rendent le meme code : une reponse qui distinguerait les deux permettrait d’enumerer les references des autres. |
Ce qui n’est pas une erreur
Un montant hors des bornes du rail rend une cotation valide, avec un objet limitError. Ce n’est pas un echec : c’est une information que votre interface doit afficher.
"limitError": { "code": "below_min", "limit": "20.00" }Traiter ce cas comme une erreur HTTP vous priverait du montant calcule, et donc de la possibilite de dire a l’utilisateur « il vous manque 16,53 EUR pour atteindre le minimum de ce moyen de paiement ». La borne s’applique au montant net, celui que recoit le beneficiaire.
Reessayer, ou pas
Trois familles, trois conduites. Reessayer une erreur de validation en boucle ne fait que remplir vos journaux.
Reessayer avec attente
rate_stale, rate_unavailable, quote_failed, et un eventuel depassement de debit. Attendez quelques secondes, avec un ecart croissant entre les tentatives. Ne comblez pas le trou avec une cotation mise en cache.
Demander une decision
rail_not_open, quote_expired, beneficiary_rejected, country_not_served. La situation demande un choix humain : proposez un autre rail, une nouvelle cotation, une correction des coordonnees.