Codes d'erreur

L'API PayerScan utilise un format de réponse d'erreur standardisé. Toutes les erreurs suivent une structure cohérente pour un traitement facile sur le backend du marchand.

Structure de réponse d'erreur

{
  "status": "error",
  "message": "Invalid API key. Please check your API key and try again.",
  "error_code": "INVALID_API_KEY",
  "request_id": "ORDER_123456",
  "details": { ... }
}

Propriétés :

• status : Toujours "error".
• message : Description de l'erreur lisible par l'humain.
• error_code : Code lisible par la machine au format UPPER_SNAKE_CASE. Utilisez switch/case pour le traitement automatisé.
• request_id (optionnel) : Votre ID de commande, retourné uniquement s'il a été fourni lors de la création de la facture.
• details (optionnel) : Contexte supplémentaire sur l'erreur (ex. : erreurs de validation, noms des champs).

Référence des codes d'erreur

Erreurs d'authentification

Code d'erreur	HTTP	Message	Résolution
MISSING_API_KEY	401	Missing API key. Please provide x-api-key header.	Ajoutez le header x-api-key à votre requête.
INVALID_API_KEY	401	Invalid API key. Please check your API key and try again.	Vérifiez votre API key sur le Dashboard.
ACCOUNT_INACTIVE	403	Merchant account is inactive. Please contact support to reactivate.	Contactez le support PayerScan.
STORE_INACTIVE	403	Store is inactive. Please contact support to reactivate your store.	Réactivez la boutique sur le Dashboard.
AUTHENTICATION_FAILED	500	Authentication failed. Please try again later.	Réessayez plus tard ; si persistant, contactez le support.

Erreurs de validation

Code d'erreur	HTTP	Message	Résolution
VALIDATION_ERROR	400	Validation failed. Please check your request body.	Vérifiez details.errors pour les problèmes spécifiques.
INVALID_MERCHANT_ID	400	Invalid merchant_id. The merchant_id does not match your API key.	Assurez-vous que merchant_id correspond à la boutique de l'API key.

Erreurs de logique métier

Code d'erreur	HTTP	Message	Résolution
INSUFFICIENT_BALANCE	402	Insufficient balance. Please top-up your account to continue.	Rechargez sur le Dashboard PayerScan. Consultez details pour le montant manquant.
NO_PAYMENT_METHOD	400	No payment method configured. Please add at least one wallet or exchange platform.	Ajoutez un portefeuille ou connectez une plateforme d'échange sur le Dashboard.

Erreurs de facture

Code d'erreur	HTTP	Message	Résolution
INVOICE_NOT_FOUND	404	Invoice not found.	Vérifiez le trans_id et assurez-vous qu'il appartient à votre boutique.
MISSING_TRANS_ID	400	Missing trans_id in URL.	Incluez trans_id dans le chemin URL : GET /invoice/:trans_id.
INVALID_TRANS_ID_FORMAT	400	Invalid trans_id format.	Utilisez le format correct : TID-XXXXXXXXXXXXXXXX.

Erreurs de limite de débit

Code d'erreur	HTTP	Message	Résolution
RATE_LIMIT_EXCEEDED	429	Too many requests per second. / Rate limit exceeded.	Attendez retry_after_seconds et réessayez. Voir Limites de débit.

Erreurs serveur

Code d'erreur	HTTP	Message	Résolution
INTERNAL_ERROR	500	Internal server error. Please try again later.	Réessayez avec un recul exponentiel. Si persistant, contactez le support.