Gestion des erreurs
Gérez correctement les erreurs de validation, d’authentification, de provider et de limites.
Votre intégration doit traiter les réponses d’erreur comme des signaux opérationnels, pas seulement comme des statuts HTTP.
Format d’erreur
{
"message": "Error description",
"errors": {
"field": ["Error message"]
}
}Codes HTTP courants
| Code | Signification |
|---|---|
| 400 | Requête invalide ou mal formée |
| 401 | Authentification absente ou invalide |
| 403 | Requête bloquée : profil d'entreprise incomplet, paiement par carte non activé, KYC non fait, ou action réservée au dashboard |
| 404 | Ressource introuvable |
| 422 | Erreur de validation, ou paiement refusé par l’opérateur ou le provider — le message en donne la raison |
| 500 | Erreur interne |
| 503 | Provider injoignable, sans réponse ou surchargé : réessayez plus tard avec le même Idempotency-Key |
Les erreurs de paiement ne sont jamais renvoyées en 502 : un 502 reçu vient du réseau situé devant l’API, pas de Genuka Pay.
Exemples
Authentification invalide
{
"message": "Unauthenticated."
}Signature fausse, timestamp décalé de plus de 5 minutes, clé publique inconnue ou inactive : tous donnent ce même 401. Vérifiez d'abord la chaîne signée (voir Authentification).
Profil d'entreprise incomplet
{
"message": "Your company profile must be completed before you can access this resource.",
"code": "COMPANY_PROFILE_INCOMPLETE",
"missing_fields": ["legal_type"]
}Complétez le profil depuis le dashboard ; les endpoints d'intégration répondent ainsi (403) tant qu'il ne l'est pas.
Erreur de validation
Code 422. message reprend la première erreur ; errors liste tous les champs invalides.
{
"message": "Le format du champ payer phone est invalide.",
"errors": {
"payer_phone": ["Le format du champ payer phone est invalide."]
}
}Erreurs de la vérification de statut
GET /api/v1/payments/status/{track_id} renvoie les erreurs côté opérateur sous la forme {"error": "...", "error_code": "..."} (TRANSACTION_NOT_FOUND, CHECK_STATUS_ERROR) plutôt qu'avec message. Voir API Paiements.
Refus KYC ou limite
Une initiation de paiement peut aussi échouer à cause des limites KYC ou AML.
Traitez ces cas comme des échecs métier nécessitant :
- notification côté merchant
- revue du compte
- éventuelle escalade KYC
Bonnes pratiques
- loggez toujours
external_id,track_idet l’endpoint ensemble - distinguez validation et erreurs retryables
- ne retryez que les erreurs transitoires
- ne retryez pas aveuglément un refus dû au KYC ou aux limites
- gardez la réconciliation séparée du flux request-response
How is this guide?
Last updated on