Catalogue des erreurs
Toutes les erreurs ont la même forme :
{ "error": { "code": "invalid_amount", "message": "..." } }Testez le code, jamais le message. Le code est stable ; le message est rédigé pour un humain et peut être reformulé sans préavis.
Toute réponse porte Valsoria-Request-Id. Il apparaît à l'identique dans le Journal API de votre console : commencez toujours par là.
Les 47 codes que l'API peut rendre
Cette liste est dérivée de la spécification, et chacun de ces codes est provoqué contre la sandbox à chaque recette. Aucun n'est théorique.
| Code | Statut | Que faire |
|---|---|---|
amount_above_limit | 422 | — |
amount_too_large | 422 | Au-delà du reste remboursable. Relisez le paiement pour connaître ce reste. |
amount_too_small | 422 | — |
authentication_required | 401 | Ajoutez l'en-tête Authorization: Bearer. |
batch_not_cancellable | 409 | — |
batch_not_executable | 409 | — |
batch_pending_approval | 409 | — |
bornes_illisibles | 500 | — |
checkout_creation_failed | 500 | — |
destination_introuvable | 404 | — |
destination_non_designee | 422 | Cette destination sert aux décaissements. La destination de vos règlements se désigne dans votre console, écran « Règlements » — une seule à la fois, par le propriétaire du compte. Rien à changer dans votre code. |
destination_trop_recente | 422 | Une destination fraîchement désignée attend un délai avant de servir. Le message indique la date. Ce délai vous laisse le temps de réagir si le changement ne venait pas de vous. |
duplicate_reference | 409 | Ce merchant_reference désigne déjà une autre transaction. |
idempotency_in_progress | 409 | Une requête identique est en cours. Attendez, ne changez pas de clé. |
idempotency_key_required | 400 | Ajoutez Idempotency-Key, dérivée de votre commande. |
idempotency_key_reused | 422 | Même clé, corps différent. Utilisez une clé par commande, pas par tentative. |
insufficient_funds | 409 | — |
insufficient_scope | 403 | — |
invalid_amount | 422 | Entier strictement positif, en unité mineure. Ni chaîne, ni décimale. |
invalid_api_key | 401 | Clé inconnue, révoquée ou malformée. Vérifiez le préfixe et l’environnement. |
invalid_beneficiary | 422 | — |
invalid_body | 400 | Le corps n’est pas du JSON valide. |
invalid_currency | 422 | Code ISO à trois lettres. |
invalid_id | 422 | L’identifiant doit être un txn_…. |
invalid_lines | 422 | — |
invalid_msisdn | 422 | — |
invalid_operator | 422 | — |
invalid_period | 422 | — |
invalid_request | 400 | — |
invalid_return_url | 422 | — |
lien_indisponible | 409 | — |
merchant_inactive | 403 | Votre dossier de vérification n’est pas validé. Rien à corriger côté code. |
method_not_allowed | 405 | — |
montant_non_eligible | 422 | — |
payment_creation_failed | 500 | — |
payment_failed | 500 | — |
payout_failed | 500 | — |
rate_limit_exceeded | 429 | — |
resource_not_found | 404 | Inconnu, ou appartenant à un autre marchand. Les deux rendent 404. |
session_closed | 409 | — |
session_expired | 409 | — |
settlement_failed | 500 | — |
sous_le_plancher | 422 | — |
statement_failed | 500 | — |
too_many_attempts | 429 | — |
too_many_lines | 422 | — |
refund_via_support | 403 | Le remboursement par API est fermé depuis le 27 août 2026 : la décision revient à LibrePay, qui le traite sur justification. Contactez le support avec l’identifiant du paiement. Retirez cet appel de votre intégration — la route n’est plus documentée. |
Ce qui mérite une nouvelle tentative
| Situation | Rejouer ? |
|---|---|
| Erreur réseau, aucune réponse | Oui, avec la MÊME clé d'idempotence |
5xx | Oui, avec la même clé |
429 | Oui, après attente |
4xx | Non — la requête est en cause, le refus serait identique |
Rejouer avec la même clé est sans danger : c'est précisément ce pour quoi l'idempotence existe. Rejouer avec une clé neuve crée un second paiement.
Version d'API 2026-08-25 ·
changements ·
spécification OpenAPI