Logo GenukaGenuka Pay
Guides

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

CodeSignification
400Requête invalide ou mal formée
401Authentification absente ou invalide
403Requête bloquée : profil d'entreprise incomplet, paiement par carte non activé, KYC non fait, ou action réservée au dashboard
404Ressource introuvable
422Erreur de validation, ou paiement refusé par l’opérateur ou le provider — le message en donne la raison
500Erreur interne
503Provider 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_id et 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