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 16 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
`already_refunded`	409	Ce paiement est déjà entièrement remboursé.
`amount_too_large`	422	Au-delà du reste remboursable. Relisez le paiement pour connaître ce reste.
`authentication_required`	401	Ajoutez l'en-tête `Authorization: Bearer`.
`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.
`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_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_payment_id`	422	Le `payment_id` doit être un `txn_…`.
`merchant_inactive`	403	Votre dossier de vérification n’est pas validé. Rien à corriger côté code.
`refund_unsupported`	422	Ce canal n’a pas d’opération inverse. Passez par un décaissement.
`resource_not_found`	404	Inconnu, ou appartenant à un autre marchand. Les deux rendent 404.

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