Erreurs

Toutes les erreurs ont la même forme. Basez votre logique sur code, qui est stable ; message est destiné aux humains et peut changer.

{ "error": { "code": "insufficient_funds", "message": "Available balance is too low for this payout", "details": null } }

HTTP	code	Signification	Que faire
400	validation_error	corps ou paramètres de requête invalides (details liste les champs), montant inférieur au minimum, starting_after inconnu	corrigez la requête ; ne la relancez pas telle quelle
400	invalid_request	la requête n’a pas pu être lue (par exemple un JSON mal formé)	corrigez la requête
401	authentication_required	pas d’en-tête Authorization: Bearer sk_…	envoyez votre clé secrète
401	invalid_api_key	clé mal formée, inconnue ou révoquée	vérifiez la clé et son mode
403	forbidden	compte suspendu, ou simulate appelé avec une clé de production	contactez Xaalis / utilisez une clé de test
403	merchant_not_active	requête en production alors que votre compte n’est pas encore active	restez en mode test jusqu’à l’activation
404	not_found	aucun objet de ce type pour le commerçant et le mode de cette clé	vérifiez l’identifiant et la clé (test ou production)
409	idempotency_conflict	Idempotency-Key réutilisée avec des paramètres différents (montant, prestataire, bénéficiaire…)	utilisez une nouvelle clé pour une requête différente
409	invalid_state	l’objet ne peut pas faire cela pour l’instant (paiement déjà dans un état final ou expiré, abonnement qui n’est plus actif, avance de test déjà en cours)	consultez l’état de l’objet ; créez-en un nouveau si nécessaire
409	key_secret_unavailable	l’émission d’une clé (clé API ou clé de portefeuille d’agent) a été relancée : un secret n’est affiché qu’une seule fois	révoquez l’identifiant de clé indiqué dans l’erreur, puis émettez-en une nouvelle avec une nouvelle Idempotency-Key
422	insufficient_funds	versement supérieur à available (frais compris)	versez un montant plus faible
422	unsupported	par exemple un versement Orange Money en production	utilisez Wave
429	rate_limited	plus de 100 requêtes par seconde sur une même clé (60/s par IP sur les routes de la page de paiement)	attendez Retry-After secondes, puis relancez
502	provider_error	Wave / Orange Money n’a pas réussi à démarrer le paiement	relancez, ou proposez l’autre moyen de paiement
503	temporarily_unavailable	une dépendance est brièvement indisponible, ou l’issue d’un versement ou d’un remboursement n’est pas encore connue	relancez avec la même Idempotency-Key
503	provider_not_configured	ce prestataire n’est pas activé sur la plateforme	proposez l’autre moyen de paiement
500	internal_error	un bug de notre côté ; request_id est inclus	relancez avec la même Idempotency-Key ; signalez le request_id

Ne relancez que les 429 (après Retry-After), les 5xx et les erreurs réseau — et uniquement avec la même Idempotency-Key. Ne relancez jamais un autre 4xx sans rien changer.