Erreurs de l'API v2
Toute erreur de l'API v2 a la même forme : un code stable, un type, un statut HTTP, un message en français et un lien doc_url vers l'entrée de cette page. Cette liste est générée depuis le code de la plateforme (relevé du 12 octobre 2026) et compte 112 codes.
Lire une erreur
HTTP/1.1 409 Conflict
{
"error": {
"code": "duplicate_reference",
"type": "conflict",
"message": "Cette référence est déjà utilisée par une autre transaction de ce service.",
"details": { "field": "reference", "transaction_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" },
"request_id": "req_01JA2QB4N8F3K2M7X9T5V1C6ZD",
"doc_url": "https://cashchap.com/docs/v2/erreurs#duplicate_reference"
}
}- Testez
error.codedans votre programme, jamais le message (il peut évoluer et contient parfois une valeur, comme un montant minimum). - Affichez
error.message: il est rédigé en français pour votre client ou votre équipe. - Les erreurs de saisie (
validation_failed) listent chaque champ fautif dansdetails.fields:field,codeetmessage. - Un paiement qui échoue après sa création n'est pas une erreur HTTP : la transaction passe à
failed(ouexpired) et sa raison est dansfailure.code, avec les mêmes codes que ci-dessous (famille Paiement refusé). - La colonne Exxx donne le code interne correspondant, celui des webhooks et de vos journaux d'API (codes internes).
Familles d'erreurs
| Type | HTTP | Conduite à tenir |
|---|---|---|
invalid_request | 400 | Corrigez la requête (JSON, en-têtes) avant de la renvoyer. |
authentication_error | 401 | Vérifiez la clé envoyée dans Authorization: Bearer et son environnement (Live ou Sandbox). |
permission_denied | 403 | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. |
not_found | 404 | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. |
conflict | 409 | Relisez l'état actuel (transaction, terminal) avant d'agir de nouveau. |
gone | 410 | La ressource n'existe plus ou ne sert plus (API v1 retirée, QR code expiré ou annulé) : voyez le conseil du code. |
validation_error | 422 | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. |
payment_failed | 402 | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. |
rate_limited | 429 | Attendez la durée de l'en-tête Retry-After (ou quelques minutes) avant de réessayer. |
api_error | 500 | Réessayez avec la même clé d'idempotence ; si l'erreur persiste, contactez le support avec le request_id. |
provider_error | 502 | L'opérateur n'a pas pu traiter l'opération : réessayez plus tard. |
service_unavailable | 503 | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. |
timeout | 504 | Réessayez avec la même clé d'idempotence : vous obtiendrez la transaction si elle a été créée. |
Requête mal formée invalid_request
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
invalid_json |
400 | Le corps de la requête doit être un objet JSON valide. | Corrigez la requête (JSON, en-têtes) avant de la renvoyer. | |
request_too_large |
413 | Le corps de la requête dépasse 32 Ko. | Corrigez la requête (JSON, en-têtes) avant de la renvoyer. | |
idempotency_key_required |
400 | L'en-tête Idempotency-Key est obligatoire pour cette opération. | Ajoutez l'en-tête Idempotency-Key (valeur unique par opération). | E312 |
invalid_idempotency_key |
400 | La clé d'idempotence doit contenir 1 à 128 caractères (lettres, chiffres, - et _). | Corrigez la requête (JSON, en-têtes) avant de la renvoyer. | E439 |
method_not_allowed |
405 | Cette méthode HTTP n'est pas acceptée sur cette route. | Corrigez la requête (JSON, en-têtes) avant de la renvoyer. |
Authentification authentication_error
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
missing_api_key |
401 | Clé API absente : envoyez l'en-tête Authorization: Bearer <clé>. | Envoyez Authorization: Bearer suivi de votre clé. | E311 |
invalid_api_key |
401 | La clé API est inconnue ou n'est plus active. Vérifiez la clé dans votre espace développeur. | Copiez de nouveau la clé depuis Développeurs › Clés API ; une clé régénérée remplace l'ancienne. | E001 |
terminal_revoked |
401 | Ce terminal a été révoqué par le marchand. Demandez un nouveau code d'activation. | Le terminal est révoqué : créez un nouveau terminal et activez-le. | |
session_expired |
401 | La session de caisse a expiré ou a été fermée. Ouvrez une nouvelle session. | Ouvrez une nouvelle session de caisse depuis votre serveur. |
Opération non permise permission_denied
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
secret_key_required |
403 | Cette opération exige la clé secrète du service, côté serveur uniquement. | Appelez cette route depuis votre serveur, avec la clé secrète. | E431 |
terminal_not_allowed |
403 | Un terminal de paiement ne peut pas effectuer cette opération. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | |
payment_method_not_allowed_on_channel |
403 | Ce moyen de paiement n'est pas accepté sur ce canal. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | |
sessions_by_terminal_disabled |
403 | L'ouverture d'une session de caisse depuis le terminal n'est pas encore disponible : ouvrez-la depuis votre serveur ou le portail. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | |
recipient_unavailable |
403 | Ce bénéficiaire est momentanément indisponible pour un retrait : notre équipe est prévenue. Vous pouvez le supprimer puis l'ajouter de nouveau dans vos comptes de retrait autorisés. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E042 |
recipient_cooling_off |
403 | Ce bénéficiaire a été ajouté il y a moins de 24 h : le premier retrait vers lui sera possible après ce délai de sécurité (heure exacte dans details.available_at, UTC). | Délai de sécurité de 24 h après l'ajout d'un bénéficiaire : réessayez après details.available_at (UTC). | E490 |
recipient_not_authorized |
403 | Ce numéro bénéficiaire n'est pas autorisé pour ce service : ajoutez-le aux comptes de retrait autorisés de votre espace. | Ajoutez le numéro aux comptes de retrait autorisés du service, puis validez-le. | |
account_not_activated |
403 | Le compte de ce service n'est pas encore activé (vérification d'identité). Utilisez la clé SANDBOX en attendant. | Utilisez la clé Sandbox en attendant la validation de votre dossier KYC. | E003 |
operator_suspended |
403 | Ce collaborateur est suspendu ou n'a pas accepté l'invitation. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E005 |
permission_denied |
403 | Vous n'avez pas l'autorisation d'effectuer cette action. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E006 |
phone_number_blocked |
403 | Ce numéro de téléphone est bloqué sur CashChap. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E011 |
operator_cannot_collect |
403 | Le rôle de ce collaborateur ne permet pas d'encaisser. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E012 |
operator_cannot_payout |
403 | Le rôle de ce collaborateur ne permet pas de faire des retraits. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E013 |
account_unavailable |
403 | Le compte de ce service est introuvable. Contactez le support CashChap. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E350 |
account_inactive |
403 | Le compte de ce service n'est pas activé. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E351 |
account_suspended |
403 | Le compte de ce service est suspendu. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E352 |
provider_not_allowed |
403 | Ce service n'est pas autorisé à utiliser cet opérateur sur ce canal. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E356 |
service_inactive |
403 | Ce service n'existe pas ou a été désactivé. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E360 |
bank_account_not_allowed |
403 | Ce compte bancaire n'est pas autorisé pour ce service. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E430 |
payout_owner_only |
403 | Seuls le titulaire du service et les administrateurs peuvent demander ou annuler un virement bancaire. | L'opération n'est pas permise à cette clé, à ce compte ou à ce collaborateur : ne réessayez pas tel quel. | E446 |
Introuvable not_found
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
route_not_found |
404 | Cette route n'existe pas dans l'API v2. Consultez la documentation. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | |
transaction_not_found |
404 | Transaction introuvable. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | E435 |
terminal_not_found |
404 | Terminal introuvable. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | |
payment_link_not_found |
404 | Lien de paiement introuvable. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | |
event_not_found |
404 | Événement introuvable. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | |
webhook_endpoint_not_found |
404 | Webhook introuvable pour ce service dans ce mode. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | |
checkout_not_found |
404 | QR code de caisse introuvable. | Vérifiez l'identifiant : un terminal ne voit que ses propres QR codes, une clé secrète ceux de son mode. | |
operator_not_found |
404 | Collaborateur introuvable pour ce service. | Vérifiez l'identifiant ou l'adresse ; une ressource d'un autre environnement est introuvable. | E004 |
Conflit conflict
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
request_in_progress |
409 | Une requête avec cette clé d'idempotence est encore en cours. Réessayez dans une seconde. | Patientez une seconde (Retry-After: 1) puis renvoyez la même requête avec la même clé. | |
idempotency_conflict |
409 | Cette clé d'idempotence a déjà servi pour une autre requête. | Une clé ne sert qu'à une opération : générez une nouvelle clé pour une nouvelle demande. | E101 |
duplicate_reference |
409 | Cette référence est déjà utilisée par une autre transaction de ce service. | Une transaction existe déjà pour cette référence : lisez-la avec details.transaction_id au lieu d'en créer une autre. | |
webhook_limit_reached |
409 | Limite de webhooks atteinte pour ce service dans ce mode. | Relisez l'état actuel (transaction, terminal) avant d'agir de nouveau. | |
payment_link_already_paid |
409 | Ce QR code a déjà été payé : il ne peut plus servir. | Ce QR code de caisse est déjà payé : lisez la transaction (GET /v2/checkouts/{id}) au lieu de faire payer de nouveau. | |
payment_link_in_progress |
409 | Un paiement est déjà en cours avec ce QR code. Patientez quelques instants. | Un autre téléphone est en train de payer ce QR code : attendez son résultat (GET /v2/checkouts/{id}?wait=5). | |
checkout_not_cancellable |
409 | Annulation impossible : le client est en train de payer ou le paiement est terminé. | Le client paie ou a payé : suivez le QR (GET /v2/checkouts/{id}?wait=5) au lieu de l'annuler. | |
cannot_cancel |
409 | Annulation impossible : la transaction est déjà en cours de traitement ou terminée. | Relisez l'état actuel (transaction, terminal) avant d'agir de nouveau. | E436 |
cannot_revoke |
409 | Ce terminal est déjà révoqué. | Relisez l'état actuel (transaction, terminal) avant d'agir de nouveau. | |
amount_changed |
409 | Le montant à payer a changé. Confirmez le nouveau montant. | Le total a changé depuis le devis : affichez details.amount_charged au client et demandez sa confirmation. | E371 |
Retiré gone
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
api_v1_removed |
410 | La version 1 de l'API CashChap a été retirée. Utilisez l'API v2 (https://api.cashchap.com/v2) : le guide de migration indique l'équivalent de chaque route. | Remplacez l'adresse /v1 par son équivalent v2 (guide « v1 retirée : migrer à la v2 », /docs/migration-v2). | |
payment_link_expired |
410 | Ce QR code a expiré : demandez un nouveau QR code au caissier. | QR code de caisse expiré : créez un nouveau QR (POST /v2/checkouts) et présentez-le au client. | |
payment_link_cancelled |
410 | Ce QR code a été annulé ou remplacé : demandez un nouveau QR code au marchand. | QR code annulé par la caisse ou QR code de la boutique remplacé : présentez le QR code actuel. |
Validation validation_error
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
validation_failed |
422 | La requête contient des champs invalides. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | |
unknown_field |
422 | Ce champ n'existe pas dans l'API v2. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | |
activation_code_invalid |
422 | Code d'activation inconnu, déjà utilisé ou expiré. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | |
payment_link_inactive |
422 | Ce lien de paiement n'est plus actif. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | |
payment_link_amount_fixed |
422 | Le montant de ce lien de paiement est fixe : il ne peut pas être modifié. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | |
invalid_metadata |
422 | Métadonnées invalides. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | |
balance_not_yet_withdrawable |
422 | Une partie de votre solde provient d'un crédit manuel récent : elle sera retirable après le délai de sécurité de 24 h (heure dans details.available_at, UTC). | Un crédit manuel récent n'est retirable qu'après 24 h : retirez un montant plus petit maintenant, ou réessayez après details.available_at (UTC). | E491 |
provider_unavailable |
422 | Ce moyen de paiement n'est pas actif pour le moment. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E008 |
currency_not_supported |
422 | Cette devise n'est pas acceptée pour ce moyen de paiement. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E009 |
invalid_phone_number |
422 | Ce numéro de téléphone n'est pas valide pour cet opérateur. | Vérifiez l'indicatif, la longueur et l'opérateur : le numéro doit être un numéro du pays de l'opérateur. Bénin : 229, puis 01 et 8 chiffres (2290197000000). | E010 |
phone_international_required |
422 | Le numéro de téléphone doit être au format international, indicatif du pays compris (exemple pour le Bénin : 2290166000000). | Envoyez le numéro avec l'indicatif du pays, sans « + », par exemple 2290166000000 pour le Bénin. country ne complète pas un numéro national. | E314 |
phone_country_mismatch |
422 | Le pays indiqué (country) ne correspond pas à l'indicatif du numéro de téléphone : le pays est déduit de l'indicatif. | Retirez country (le pays est déduit de l'indicatif) ou corrigez le numéro. | E315 |
unsupported_payment_method |
422 | Moyen de paiement inconnu : utilisez mobile_money, card ou direct_debit. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E102 |
invalid_amount |
422 | Le montant est requis et doit être un nombre supérieur à 0. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E300 |
provider_required |
422 | L'opérateur (provider) est requis. | Indiquez provider, ou « auto » avec un numéro reconnu ; si le numéro ne correspond à aucun opérateur ou à plusieurs, vérifiez-le ou précisez l'opérateur. | E301 E480 E481 |
currency_required |
422 | La devise est requise (code ISO 4217, ex. XOF). | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E302 |
card_cvv_required |
422 | Le code de sécurité de la carte est requis. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E303 |
card_expiry_required |
422 | La date d'expiration de la carte est requise. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E304 |
card_number_required |
422 | Le numéro de carte est requis. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E305 |
phone_required |
422 | Le numéro de téléphone est requis. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E306 |
customer_required |
422 | Les informations du client sont requises. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E307 |
customer_name_required |
422 | Le nom du client est requis (255 caractères au plus). | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E308 |
invalid_email |
422 | L'adresse e-mail est invalide. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E309 |
invalid_reference |
422 | La référence (reference) est invalide : 1 à 64 caractères (lettres, chiffres, _ . : / -). | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E310 |
amount_too_small |
422 | Le montant minimum d'un encaissement est de …. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E357 |
amount_too_large |
422 | Le montant maximum d'un encaissement est de …. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E358 |
amount_below_fees |
422 | Le montant ne couvre pas les frais. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E372 |
payout_currency_not_supported |
422 | Seuls les retraits en XOF sont acceptés. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E373 |
amount_too_many_decimals |
422 | Le montant a trop de décimales pour la devise …. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E374 |
payout_amount_too_small |
422 | Le montant minimum d'un retrait est de …. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E375 |
payout_amount_too_large |
422 | Le montant maximum d'un retrait est de …. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E376 |
payout_amount_out_of_range |
422 | Montant hors limites pour un virement bancaire. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E432 |
bank_account_ambiguous |
422 | Plusieurs comptes bancaires correspondent : précisez bank_account_id. | Corrigez le champ indiqué dans details.field ou details.fields ; la clé d'idempotence est libérée. | E434 |
insufficient_balance |
422 | Votre solde disponible est insuffisant pour ce retrait. | Votre solde disponible ne couvre pas le retrait (fonds en cours non compris). | E437 |
Paiement refusé payment_failed
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
customer_declined |
402 | Le client a refusé ou annulé le paiement sur son téléphone. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E410 |
customer_timeout |
402 | Le client n'a pas validé le paiement à temps. | Le client n'a pas validé à temps (statut expired) : proposez-lui de recommencer. | E411 |
insufficient_funds |
402 | Le solde Mobile Money du client est insuffisant. | Le client doit recharger son compte Mobile Money ou payer autrement. | E412 |
customer_limit_reached |
402 | Le compte Mobile Money du client a atteint son plafond. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E413 |
customer_not_registered |
402 | Ce numéro n'est pas inscrit au Mobile Money. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E414 |
operation_not_allowed |
402 | L'opérateur n'autorise pas cette opération sur le compte du client. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E415 |
amount_not_allowed |
402 | L'opérateur n'autorise pas ce montant pour le compte du client. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E416 |
recipient_not_registered |
402 | Le numéro bénéficiaire n'est pas inscrit au Mobile Money. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E420 |
recipient_not_allowed |
402 | Le numéro bénéficiaire ne peut pas recevoir ce retrait. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E421 |
recipient_limit_reached |
402 | Le compte bénéficiaire ne peut pas recevoir ce montant. | Échec côté client ou opérateur, visible dans failure d'une transaction : proposez au client de réessayer ou un autre moyen. | E422 |
Trop de requêtes rate_limited
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
rate_limited |
429 | Trop de requêtes. Réessayez dans quelques instants. | Attendez la durée de l'en-tête Retry-After (ou quelques minutes) avant de réessayer. | E470 |
too_many_pending_for_phone |
429 | Trop de demandes de paiement pour ce numéro. Réessayez plus tard. | Laissez au client le temps de valider ses demandes en cours ; réessayez dans quelques minutes. | E472 |
sandbox_rate_limited |
429 | Limite de transactions de test atteinte. Réessayez plus tard. | Attendez la durée de l'en-tête Retry-After (ou quelques minutes) avant de réessayer. | E031 |
too_many_pending_payouts |
429 | Trop de virements bancaires en attente. Attendez leur traitement. | Attendez la durée de l'en-tête Retry-After (ou quelques minutes) avant de réessayer. | E433 |
Erreur CashChap api_error
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
not_implemented |
501 | Cette opération n'est pas encore disponible dans l'API v2. | Opération prévue mais pas encore ouverte dans l'API v2 : utilisez le portail. | |
internal_error |
500 | Une erreur interne est survenue. Réessayez avec la même clé d'idempotence. | Réessayez avec la même clé d'idempotence ; si l'erreur persiste, contactez le support avec le request_id. | E100 E999 |
upstream_unavailable |
502 | Le service de paiement est momentanément injoignable. Réessayez avec la même clé d'idempotence. | Réessayez avec la même clé d'idempotence ; une alerte est déjà envoyée à l'équipe CashChap. |
Erreur de l'opérateur provider_error
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
provider_error |
502 | L'opérateur n'a pas pu effectuer l'opération. | L'opérateur n'a pas pu traiter l'opération : réessayez plus tard. | E419 E429 |
Service indisponible service_unavailable
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
service_disabled |
503 | L'API v2 est momentanément indisponible. Réessayez dans quelques minutes. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | |
webhooks_unavailable |
503 | La gestion des webhooks est momentanément indisponible. Réessayez dans quelques minutes. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | |
service_temporarily_blocked |
503 | Ce service est temporairement bloqué par un contrôle de sécurité. Notre équipe est prévenue et vous recontactera. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | E040 |
service_maintenance |
503 | CashChap est en maintenance pour ce service. Réessayez dans quelques minutes. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | E002 |
card_payments_unavailable |
503 | Le paiement par carte est momentanément indisponible. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | E007 |
sandbox_unavailable |
503 | Le mode test (SANDBOX) est momentanément indisponible pour ce service. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | E030 |
exchange_rate_unavailable |
503 | Le taux de change est momentanément indisponible. Réessayez plus tard ou payez dans une autre devise. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | E370 |
payouts_temporarily_unavailable |
503 | Les retraits sont momentanément indisponibles. Réessayez plus tard. | Rien n'a été débité : réessayez dans quelques minutes. | E041 E423 E477 |
bank_payouts_unavailable |
503 | Les virements bancaires sont momentanément indisponibles. | Service momentanément fermé : réessayez plus tard, avec la même clé d'idempotence. | E438 |
Délai dépassé timeout
| Code | HTTP | Message | Que faire | Exxx |
|---|---|---|---|---|
upstream_timeout |
504 | Le service de paiement ne répond pas à temps. Réessayez avec la même clé d'idempotence. | Réessayez avec la même clé d'idempotence : vous obtiendrez la transaction si elle a été créée. |
Codes de champ
Ces codes n'apparaissent que dans details.fields[].code d'une erreur validation_failed (422) :
| Code | Champ | Valeur attendue |
|---|---|---|
invalid_cursor | cursor | Curseur de pagination invalide : reprenez meta.next_cursor de la page précédente. |
invalid_date | created_after, created_before | Date ISO 8601 attendue, par exemple 2026-10-10T14:46:27Z. |
invalid_limit | limit | Entier de 1 à 100. |
invalid_status | status | pending, succeeded, failed, cancelled ou expired. |
invalid_type | type | collection ou payout. |
invalid_channel | channel | api, widget, payment_link, shop, pos ou dashboard. |
invalid_terminal_id | terminal_id | Identifiant (UUID) de terminal attendu. |
invalid_wait | wait | Nombre de secondes entre 0 et 20. |
invalid_expires_in | expires_in | Durée de validité d'un QR de caisse : entier de 60 à 900 secondes. |
invalid_format | format, width | format vaut json ou text ; width vaut 32 ou 48. |
invalid_operation | operation | collection ou payout. |
invalid_kind | kind | Type de terminal : pos ou shop. |
invalid_label | label | Nom du terminal requis, 80 caractères au plus. |
invalid_ttl | ttl_minutes | Durée de la session : entier de 1 à 480 minutes. |
invalid_device | device | Objet { model, serial } de textes courts. |
Quand réessayer ?
- Oui, avec la même
Idempotency-Key: 5xx (internal_error,upstream_unavailable,upstream_timeout,service_disabled), 409request_in_progress, coupure réseau. Vous n'obtiendrez jamais deux transactions. - Oui, plus tard : 429 (respectez
Retry-After), 503payouts_temporarily_unavailable,sandbox_unavailable. - Non, pas tel quel : 400, 401, 403, 404, 422 (corrigez d'abord), 409
duplicate_referenceetidempotency_conflict. - Paiement refusé (
failed) : une nouvelle tentative est un nouveau paiement, avec une nouvelle clé d'idempotence et l'accord du client.