Concepts

Erreurs

Le format des erreurs, leurs types et leurs codes.

Monerail utilise les codes HTTP : 2xx signifie que tout s’est bien passé, 4xx que la requête ne peut pas réussir telle quelle, 5xx qu’un problème est survenu chez nous ou chez un partenaire. Les erreurs ont toujours la même forme :

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "amount must be an integer between 1 and 100000000000 (minor units)",
    "param": "amount",
    "request_id": "req_3aec3e6d1222495eb183"
  }
}

Champ	Description
`type`	Famille de l’erreur (tableau ci-dessous).
`code`	Raison précise et stable : c’est sur lui que votre code doit se brancher.
`message`	Explication pour un développeur. Il peut changer : ne l’analysez pas. En anglais par défaut, en français avec `Accept-Language: fr`.
`param`	Le paramètre en cause, s’il y en a un.
`object_id`, `card`	L’objet créé avant l’échec, s’il existe (par exemple une carte refusée par l’émetteur).
`request_id`	À donner au support.

Les messages ne contiennent jamais de détail interne ou de partenaire. Une requête refusée pour une raison sans code propre renvoie 400 request_invalid avec le message « The request could not be processed. Check the parameters. » (en français avec Accept-Language: fr). Les erreurs 5xx ont toujours un message générique. Les refus d’un opérateur ou de l’émetteur de cartes gardent leur motif, sous 402 provider_declined.

Codes HTTP

Code	Sens
`200`	OK.
`201`	Créé.
`202`	Accepté : l’opération est partie et son résultat n’est pas encore définitif. Suivez-la par webhook.
`400`	Requête invalide.
`401`	Clé absente ou invalide.
`402`	Requête valide mais impossible à exécuter.
`403`	Interdit.
`404`	Objet ou point d’accès inconnu.
`409`	Conflit, par exemple une autre opération en cours.
`422`	Clé d’idempotence réutilisée avec d’autres paramètres.
`429`	Trop de requêtes.
`5xx`	Chez nous ou chez un partenaire. Réessayez avec la même `Idempotency-Key`.

Types

Type	HTTP	Description
`invalid_request_error`	400, 404, 405, 409, 413	La requête est incorrecte : paramètre manquant ou invalide, objet ou point d’accès inconnu.
`authentication_error`	401	Clé absente, invalide, révoquée ou orpheline.
`permission_error`	403	Le créateur de la clé n’a pas le rôle requis, l’entreprise est suspendue ou la production n’est pas encore ouverte.
`request_failed`	402	Requête valide mais impossible à exécuter : solde insuffisant, refus de l’opérateur ou de l’émetteur de cartes, mauvais code.
`idempotency_error`	409, 422	L’`Idempotency-Key` est encore en cours d’utilisation ou a servi avec d’autres paramètres.
`rate_limit_error`	429	Trop de requêtes. Attendez `Retry-After` secondes. Voir Limites de débit.
`api_error`	500, 502, 503	Un problème chez nous ou chez un partenaire. Le message est toujours générique. Réessayez avec la même `Idempotency-Key`.

Codes

Code	HTTP	Description
`api_key_invalid`	401	Clé absente, mal formée, inconnue ou révoquée.
`api_key_owner_removed`	401	Le membre qui a créé la clé a quitté l’entreprise. Créez une nouvelle clé.
`account_suspended`	403	Le compte de l’entreprise est suspendu.
`permission_denied`	403	Le créateur de la clé n’a pas le rôle requis pour cette opération.
`live_mode_unavailable`	403	La production ouvre une fois votre dossier d’entreprise validé.
`parameter_missing`	400	Un paramètre requis manque. Voir `param`.
`parameter_invalid`	400	Un paramètre a un type ou une valeur incorrects. Voir `param`.
`parameter_unknown`	400	Le corps contient un paramètre que le point d’accès n’accepte pas.
`body_invalid`	400	Le corps n’est pas un objet JSON.
`body_too_large`	413	Le corps dépasse 12 Mo.
`resource_missing`	404	Aucun objet avec cet identifiant dans ce mode.
`route_unknown`	404	Point d’accès inconnu.
`method_not_allowed`	405	Le point d’accès existe, mais pas avec cette méthode HTTP.
`idempotency_key_invalid`	400	La clé dépasse 255 caractères.
`idempotency_key_in_use`	409	Une requête avec cette clé est encore en cours.
`idempotency_key_reused`	422	Cette clé a déjà servi avec d’autres paramètres.
`currency_unsupported`	400	Cette devise n’est pas ouverte.
`country_unsupported`	400	Ce pays n’est pas ouvert pour cette devise. Voir Couverture.
`bank_transfer_unsupported`	400	Les virements bancaires ne sont pas disponibles dans ce pays : payez vers un portefeuille mobile money.
`test_phone_required`	400	Mode test : utilisez un des numéros de test de ce pays. Voir Tests.
`otp_not_expected`	400	Cet encaissement n’attend pas de code (déjà validé, ou pas de code requis).
`amount_invalid`	400	Montant hors limites, par exemple une recharge de carte au-delà de 100 000 $, ou un montant en CDF qui n’est pas en francs entiers.
`amount_too_small`	400, 402	Montant inférieur au minimum (pour les cartes : frais d’émission plus 1 $).
`amount_too_large`	402	Montant supérieur au maximum de l’opérateur.
`operator_unsupported`	400, 402	Opérateur inconnu, ou refusé par le partenaire de paiement pour cette devise.
`phone_invalid`	400	Le numéro ne peut pas être lu comme un numéro international.
`bank_account_invalid`	400	`bank_code` ne correspond pas exactement à un code de Lister les banques, ou le numéro de compte est trop court.
`balance_insufficient`	402	Votre solde (ou solde cartes) ne couvre pas le montant et les frais.
`recipient_invalid`	402	Le partenaire de paiement a refusé le bénéficiaire.
`otp_invalid`	400, 402	Code erroné, mal formé ou expiré.
`provider_declined`	402	L’opérateur ou l’émetteur de cartes a refusé. `message` donne leur motif.
`settlement_destination_missing`	400	Aucun compte de reversement enregistré pour cette devise.
`settlement_destination_invalid`	400	Le compte de reversement enregistré n’est pas valide pour le partenaire de paiement.
`cardholder_exists`	409	Un titulaire utilise déjà cet e-mail.
`cardholder_not_verified`	400	L’identité du titulaire n’est pas encore vérifiée.
`id_document_unsupported`	400	Type de pièce d’identité non pris en charge.
`document_invalid`	400	La pièce enregistrée n’a pas pu être lue. Renvoyez la vérification.
`agent_cards_not_enabled`	400	Les cartes agent ne sont pas encore configurées. Un Propriétaire doit émettre la première carte agent depuis le tableau de bord.
`card_not_ready`	400	La carte n’est pas encore émise.
`card_terminated`	400	La carte est résiliée.
`card_already_frozen`	400	La carte est déjà bloquée.
`card_not_frozen`	400	La carte n’est pas bloquée.
`card_minimum_balance`	400	Au moins 1 $ doit rester sur la carte.
`card_single_use`	400	Les cartes à usage unique ne peuvent être ni rechargées ni vidées.
`card_operation_in_progress`	409	Une autre opération est en cours sur cette carte. Réessayez dans quelques secondes.
`url_invalid`	400	Pas une adresse HTTPS avec un nom de domaine, ou elle contient `utilisateur:mot_de_passe@`. Les adresses IP sont refusées.
`events_invalid`	400	Un motif d’événement est mal formé.
`limit_reached`	400	Votre entreprise a déjà 10 points de terminaison (test et production confondus).
`request_invalid`	400	Autre requête invalide. Le message est générique : « The request could not be processed. Check the parameters. »
`verification_not_submitted`	400	L’outil de test demande d’abord une vérification envoyée.
`test_mode_only`	400	Les outils de test demandent une clé de test.
`rate_limited`	429	Une limite de débit est atteinte. Attendez `Retry-After` secondes. Voir Limites de débit.
`provider_unavailable`	503	Ce service n’est pas encore ouvert dans ce mode.
`provider_insufficient_funds`	503	Le partenaire de paiement ne peut pas traiter ce paiement pour l’instant. Réessayez plus tard.
`provider_error`	502	Un partenaire est injoignable. Réessayez avec la même Idempotency-Key.
`upload_failed`	500	L’envoi de la pièce a échoué. Réessayez.
`internal`	500	Erreur inattendue. Réessayez ; contactez le support avec le `request_id` si elle persiste.

Limites de débit

Les requêtes au-delà d’une limite échouent avec 429 rate_limited et un en-tête Retry-After. Les limites sont détaillées dans Limites de débit.

Erreurs

Codes HTTP#

Types#

Codes#

Limites de débit#

Codes HTTP

Types

Codes

Limites de débit