Erreurs

Chaque refus sur /v1 répond en JSON avec le corps Error. Décidez selon error.code : il est stable, catalogué et en majuscules. Les refus propres à l’API marchande ne portent que le code ; un refus qu’elle relaie depuis le switch garde les message_en et message_fr que le switch a donnés, comme ci-dessous. Les refus propres à une route de versement répondent MerchantPayoutError, le même corps avec un shortfall : ce qui manque au solde de versement pour INSUFFICIENT_PAYOUT_BALANCE, null pour tout autre code, comme le montre le guide des versements. Les refus propres à une route de facture répondent MerchantInvoiceError, le même corps avec message_en et message_fr toujours donnés, comme le montre le guide des factures.

{
  "error": {
    "code": "SWITCH_UNAVAILABLE",
    "message_en": "Retry with the same key",
    "message_fr": "Réessayez avec la même clé"
  }
}

Chaque réponse authentifiée de /v1 porte X-Request-Id, l’identifiant que le journal des requêtes garde pour cet appel : donnez-le quand vous posez une question sur un appel. Une requête refusée avant tout routage, par exemple par le pare-feu, répond {timestamp, status, error, path} à la place, et aucune page n’est jamais en HTML.

Un 503 peut laisser le résultat inconnu : réessayez exactement la même requête avec son Idempotency-Key d’origine, qui ne crée jamais un second paiement ni un second versement, et lisez le paiement ou le versement avant d’en créer un autre.

Codes par statut

400 Requête incorrecte

Code	Quand
INVALID_REQUEST	La requête enfreint le contrat : un champ, un en-tête ou un paramètre manquant ou mal formé, ou un autre refus du framework sans code propre.
INVALID_CURSOR	La liste des livraisons n’a pas scellé ce curseur.

401 Non authentifié

Code	Quand
INVALID_API_KEY	La clé manque, est inconnue, révoquée ou de production ; elle est vérifiée à chaque requête, reprises comprises.

403 Interdit

Code	Quand
INSUFFICIENT_SCOPE	La clé n’a pas la permission que la route exige, ou aucune règle de permission ne couvre la route.
SCOPE_ESCALATION	Une clé a demandé des permissions au-delà des siennes, dont keys:manage, qu’aucune clé n’accorde jamais, y compris en renouvelant une clé qui la détient.

404 Introuvable

Code	Quand
PAYMENT_NOT_FOUND	Le paiement est inconnu ou appartient à un autre commerce.
ROUTE_NOT_FOUND	Aucune route ne répond à cette adresse sous un préfixe couvert.
LINK_NOT_FOUND	Le lien de paiement est inconnu ou appartient à un autre marchand, ou le curseur d’une liste ne désigne aucun lien de ce marchand.
BRANCH_NOT_FOUND	Le point de vente indiqué pour un nouveau lien n’est pas celui de ce marchand.
PAYOUT_NOT_FOUND	Le versement est inconnu ou appartient à un autre marchand, ou le curseur d’une liste ne désigne aucun versement de ce marchand.
PAYOUT_BATCH_NOT_FOUND	Le lot de versements est inconnu ou appartient à un autre marchand, ou le curseur d’une liste ne désigne aucun lot de ce marchand.
PAYOUT_LINE_NOT_FOUND	La ligne du lot est inconnue ou appartient à un autre marchand, ou un curseur ne désigne aucune ligne de ce lot.
NAME_ENQUIRY_NOT_FOUND	La vérification de nom qu’indique un versement est inconnue ou appartient à un autre marchand.
INVOICE_BATCH_NOT_FOUND	Le lot de factures est inconnu ou appartient à un autre marchand, ou le curseur d’une liste ne désigne aucun lot de ce marchand.
INVOICE_NOT_FOUND	La facture est inconnue ou appartient à un autre marchand, ou le curseur d’une liste ne désigne aucune facture de ce lot.

405 Méthode non autorisée

Code	Quand
METHOD_NOT_ALLOWED	La route ne répond pas à cette méthode ; Allow liste celles qu’elle accepte.

406 Non acceptable

Code	Quand
NOT_ACCEPTABLE	La route ne peut pas produire ce que demande Accept.

409 Conflit

Code	Quand
IDEMPOTENCY_CONFLICT	L’Idempotency-Key appartient déjà à une autre requête ou à un autre mode, la clé d’une commande de versement a servi pour la première fois il y a plus de 720 heures, ou une tranche de factures porte d’autres factures sous un numéro que le lot a déjà reçu.
METHOD_UNAVAILABLE	Une nouvelle admission directe est refusée : sa méthode n’est pas disponible. Rien n’est conservé.
PARTICIPANT_CAP_EXCEEDED	Une nouvelle admission directe est refusée : le plafond du participant est atteint. Rien n’est conservé.
INTENT_EXPIRED	Une nouvelle admission directe est refusée : l’intention a expiré. Rien n’est conservé.
DIRECT_PAYMENT_NOT_ADMITTED	Une nouvelle admission directe est refusée. Rien n’est conservé.
BRANCH_ARCHIVED	Une nouvelle admission directe est refusée : le point de vente est archivé. Rien n’est conservé.
MERCHANT_LIMIT_EXCEEDED	Au-delà du plafond par paiement du commerce, de son plafond du jour ou du mois, heure de Kinshasa, pour un paiement direct, de son plafond de remboursements du jour, ou de ses plafonds de versement, par versement ou par jour.
PARTICIPANT_LIMIT_EXCEEDED	Un paiement direct au-delà du maximum par transaction du participant.
PAYMENT_NOT_CANCELLABLE	L’intention a été soumise, est incertaine, terminée ou expirée, ou un autre original détient la clé.
REFUND_AMOUNT_EXCEEDED	Le remboursement demande plus qu’il ne reste à rembourser.
PAYMENT_NOT_REFUNDABLE	Le paiement n’est pas approuvé.
REFUND_METHOD_UNSUPPORTED	La méthode du paiement ne peut pas encore être remboursée.
REFUND_WINDOW_EXPIRED	Le paiement a été approuvé il y a plus de 180 jours.
LINK_NOT_CANCELLABLE	Le lien est payé ou expiré, ou une tentative est en cours ; annuler à nouveau un lien annulé le renvoie tel quel.
LINK_NOT_SHAREABLE	Le lien n’est plus payable.
EVENT_NOT_SUBSCRIBED	L’événement à renvoyer est hors de l’abonnement actuel.
WEBHOOK_CHANGED	La configuration des webhooks a changé depuis la version envoyée : relisez-la.
STATEMENT_UNAVAILABLE	Un lot antérieur à l’enregistrement des relevés n’en a pas.
STATEMENT_TOO_LARGE	Le relevé compterait plus de 10 000 lignes.
INSUFFICIENT_PAYOUT_BALANCE	Le solde de versement disponible ne couvre pas les montants et les frais du versement ou du lot : shortfall indique ce qui manque. Rien n’est réservé.
NAME_ENQUIRY_STALE	La vérification de nom du versement date de plus de 24 heures.
NAME_ACKNOWLEDGEMENT_REQUIRED	La vérification n’a pas pu donner le nom du titulaire et le versement n’en prend pas acte.
PAYOUT_DESTINATION_UNKNOWN	Le participant ne connaît pas le compte de destination du versement.
PAYOUT_ROUTE_UNAVAILABLE	Le participant ne reçoit pas de versements pour le moment, ou une décision accepte ou garde une ligne ROUTE_PAUSED.
PAYOUTS_HELD	Futa suspend les versements du marchand : rien n’est envoyé ni approuvé.
PAYOUT_BATCH_TOO_LARGE	Les lots de versements ouverts du marchand ont atteint leur limite de 20, ou les lignes d’un envoi dépasseraient celles que le lot a annoncées, ou toutes sont arrivées.
PAYOUT_BATCH_INVALID	Une ligne est dans une autre devise ou numérotée au-delà de celles annoncées ou reçues, une décision ne convient pas à sa ligne, une soumission n’a aucune ligne valide, ou le lot garderait un préparateur ou un détenteur de clé de plus qu’il ne peut.
PAYOUT_BATCH_NOT_VALIDATED	Le lot n’est pas VALIDATED : ses lignes arrivent encore ou sont en cours de vérification, il a été soumis ou est caduc, ou des lignes restent à revoir à la soumission.
PAYOUT_BATCH_CHANGED	La version du lot n’est plus celle que vous avez envoyée : relisez-le.
PAYOUT_LINE_NOT_RETRYABLE	Le lot n’a plus de ligne échouée qu’une relance puisse envoyer.
RESULT_NOT_READY	Le lot n’a pas atteint l’état que décrit son rapport ou son résultat.
INVOICE_BATCH_LIMIT_REACHED	Les lots de factures ouverts du marchand, ceux MAPPING, VALIDATING, RECEIVING ou READY, ont atteint leur limite de 20 (SYNTHETIC).
INVOICE_BATCH_TOO_LARGE	Une facture d’une tranche est numérotée au-delà de celles que le lot a annoncées, ou a été reçue dans une autre tranche.
INVOICE_BATCH_CHANGED	La version du lot n’est plus celle que vous avez envoyée, ou le lot n’accepte plus cette commande : ses factures sont toutes arrivées, il vient d’un fichier, ou il est en cours d’envoi, a été envoyé, a échoué à l’envoi, est caduc ou a été annulé. Relisez-le.
INVOICE_BATCH_NOT_VALIDATED	Le lot ne peut pas encore être envoyé : ses factures ne sont pas toutes arrivées, le mappage de son fichier n’est pas confirmé ou est en cours de vérification, ou aucune facture n’est prête.
MESSAGES_NOT_CONFIGURED	Un canal a été choisi hors du bac à sable, où aucun transport de messages n’existe encore.
MERCHANT_NAME_INVALID	Le nom enregistré du marchand ne respecte pas la règle des textes, au plus 120 points de code une fois rogné : l’envoi est refusé avant que rien ne soit créé.

413 Contenu trop volumineux

Code	Quand
EXPORT_TOO_LARGE	L’export est trop volumineux : resserrez les filtres. Aucun fichier n’est renvoyé.
REQUEST_TOO_LARGE	Le corps dépasse 16 Kio, corps fragmentés compris, sur un POST /v1 qui ne borne pas lui-même son corps, ou 512 Kio pour un envoi de lignes d’un lot de versements ou pour une tranche de factures ; il est refusé avant d’être lu.

415 Type de média non pris en charge

Code	Quand
UNSUPPORTED_MEDIA_TYPE	Le corps de la requête n’est pas du JSON.

429 Trop de requêtes

Code	Quand
RATE_LIMITED	Le quota partagé du commerce est épuisé pour le moment.
NAME_ENQUIRY_RATE_LIMITED	Le budget de vérifications de nom du marchand sur l’heure glissante est épuisé, pour une destination, une personne ou une clé, ou le marchand ; Retry-After donne les secondes à attendre.

500 Erreur interne du serveur

Code	Quand
INTERNAL_ERROR	Une défaillance inattendue, journalisée et jamais détaillée.

503 Service indisponible

Code	Quand
SWITCH_UNAVAILABLE	Le switch n’a pas répondu : le résultat peut être inconnu. Réessayez exactement la même requête avec sa clé d’origine.
INVALID_CREATION_RESPONSE	La réponse du switch à une création n’était pas valide : le résultat peut être inconnu. Réessayez avec la clé d’origine.
INVALID_CANCELLATION_RESPONSE	La réponse du switch à une annulation n’était pas valide : le résultat peut être enregistré. Réessayez avec la clé d’origine.
INVALID_LINK_RESPONSE	La réponse du switch n’avait pas la forme fermée d’un lien : rien n’en est relayé. Réessayez, une création avec sa clé d’origine.
SERVICE_UNAVAILABLE	Une réponse asynchrone a dépassé son délai.
TOP_UP_UNAVAILABLE	Le simulateur de la banque sponsor du bac à sable n’a pas répondu à une alimentation, ou le bac à sable n’a pas de clé de simulateur : le résultat peut être inconnu. Renvoyez la même requête avec la même clé, qui n’alimente qu’une fois au plus.

Les codes que le contrat ne nomme pas encore

L’API marchande répond aussi ces codes sur /v1, que le contrat public ne nomme pas encore. La publication du catalogue complet des codes reste à faire ; d’ici là, décidez selon eux comme selon les autres.

Code	Statut	Quand
EVENT_NOT_FOUND	404	L’événement dont vous lisez les tentatives ou que vous renvoyez n’est pas à ce commerce.
INVALID_RECEIPT_REQUEST	400	Un reçu a été demandé avec une requête autre que lang=fr ou lang=en.
KEY_NOT_FOUND	404	La clé à renouveler ou révoquer n’est pas à ce commerce.
KEY_REVOKED	409	La clé à renouveler est révoquée.
MERCHANT_NOT_FOUND	404	Le commerce est désactivé, pour la gestion des clés et des webhooks.
REPLAY_RATE_LIMITED	429	L’événement a déjà été renvoyé dans la dernière minute.
WEBHOOK_ALREADY_CONFIGURED	409	Le commerce a déjà un point de réception : déplacez-le avec POST /v1/webhooks/endpoint/configuration.
WEBHOOK_NOT_FOUND	404	Le commerce n’a pas encore de point de réception.

Le contrat complet indique les refus de chaque opération dans la référence de l’API (en anglais).