Documentation / Référence
Codes d'erreur
Le corps d'une erreur a toujours la même forme. Fiez-vous au code, pas au texte : le message est rédigé pour un humain et peut évoluer.
JSON
{ "error": { "code": "duplicate_order", "message": "Une facture existe déjà pour cet order_id" } }Quand relancer sans risqueEn cas de
429, 500, 503, idempotency_in_progress ou d'erreur réseau, avec le même Idempotency-Key : aucun doublon ne sera créé.Requête et accès
| HTTP | code | Cause et marche à suivre |
|---|---|---|
| 400 | bad_json, bad_body | Corps non JSON, champs superflus ou montant passé en nombre au lieu d'une chaîne : corrigez la requête |
| 400 | bad_idempotency_key | Clé absente ou mal formée : 8 à 128 caractères ASCII imprimables, ne commençant pas par d: |
| 400 | bad_query | Paramètres de liste invalides |
| 401 | unauthorized | Signature, horodatage, nonce ou clé : voir CP-HMAC |
| 403 | merchant_suspended | Compte marchand suspendu : contactez le support |
| 403 | merchant_not_approved | Inscription inachevée ou demande en cours d'examen : terminez l'assistant dans le tableau de bord |
| 403 | billing_suspended | Facture de commission impayée : réglez-la dans le tableau de bord, rubrique « Facturation » ; la suspension est levée immédiatement |
| 404 | not_found | La facture n'existe pas ou appartient à un autre marchand |
| 413 | body_too_large | Corps au-delà de la limite : réduisez metadata |
| 429 | rate_limited | Trop de requêtes : relancez avec un délai exponentiel |
| 500 | internal | Erreur interne : relancez avec le même Idempotency-Key |
Factures et idempotence
| HTTP | code | Cause et marche à suivre |
|---|---|---|
| 409 | duplicate_order | order_id déjà utilisé : prenez-en un nouveau, par exemple ORDER-1001-2 |
| 409 | idempotency_conflict | Même clé avec un corps différent |
| 409 | idempotency_in_progress | La première requête est encore en cours : relancez dans 1 à 2 s |
| 409 | invoice_not_payable | Facture expirée ou clôturée : créez-en une nouvelle |
| 422 | invalid_order_id, invalid_price_amount, invalid_price_currency, invalid_return_url, invalid_expires_in_seconds, invalid_metadata | Le champ n'a pas passé la validation : le message indique la règle |
| 422 | invalid_allowed_assets | Aucun actif de la liste n'est disponible : le message donne la raison pour chacun |
| 422 | no_assets | Aucun actif disponible : vérifiez les portefeuilles et les actifs dans le tableau de bord |
| 422 | amount_too_small | Montant inférieur au minimum de tous les actifs disponibles |
Choix de la devise sur la page de paiement
Ces erreurs sont gérées par la page de paiement ; votre serveur ne les rencontre que si vous appelez select vous-même.
| HTTP | code | Cause |
|---|---|---|
| 409 | asset_locked | Changement de devise après un paiement |
| 409 | wallet_not_configured | Aucun portefeuille de réception actif sur ce réseau |
| 409 | wallet_changed, address_conflict | Refaire le choix |
| 422 | asset_not_allowed | Actif absent de la facture ou plus autorisé |
| 503 | rate_unavailable | Aucun cours confirmé : proposez un stablecoin |
| 503 | network_unavailable | Réception temporairement indisponible sur ce réseau : choisissez-en un autre |
Remboursements
| HTTP | code | Cause |
|---|---|---|
| 403 | merchant_inactive | Boutique suspendue ou clé révoquée |
| 409 | invoice_not_paid | Aucun actif choisi sur la facture : rien à rembourser |
| 409 | nothing_to_refund | Tout a déjà été remboursé ou demandé |
| 409 | too_many_refunds | 20 demandes ouvertes sur la facture |
| 409 | refund_executor | Le remboursement est exécuté par la plateforme, pas par vous |
| 409 | invoice_status_changed | Le statut de la facture a changé depuis la demande : relancez avec "ack_status_change": true |
| 422 | amount_exceeds_refundable | Montant supérieur au disponible : réduisez-le ou utilisez "full" |
| 422 | invalid_amount, invalid_address, invalid_tx_hash | Le champ n'a pas passé la validation |