Erreurs et idempotence

Format des erreurs

La spécification OpenAPI ne documente actuellement aucun schéma formel et exploitable par machine pour le corps des erreurs — chaque réponse d'erreur est définie uniquement par une chaîne description d'une ligne (par ex. "Bad Request", "Unauthorized"), sans schéma de corps de réponse. En pratique, l'API renvoie les détails d'erreur au format JSON, selon une forme proche de RFC 7807 Problem Details, par exemple :

{
  "type": "https://api.kartapay.me/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "purchase.total.value must be a positive integer string"
}

Considérez ceci comme illustratif plutôt que garanti — les champs exacts renvoyés peuvent varier, car la spécification ne les fixe pas. Fiez-vous au minimum au code de statut HTTP ci-dessous ; utilisez le contenu du corps JSON (s'il est présent) pour la journalisation/le débogage, pas pour le contrôle de flux.

Codes de statut documentés dans la spécification OpenAPI que vous devez gérer explicitement :

Statut	Signification
400	Requête invalide — la requête était mal formée ou a échoué à la validation
401	Jeton d'accès manquant ou expiré — demandez-en un nouveau (voir Authentification)
403	Jeton valide mais non autorisé pour cette ressource
404	Ressource introuvable
500	Erreur interne du serveur — réessayez plus tard ; contactez le support si le problème persiste

Idempotence

Utilisez un clientId unique par paiement (voir Créer un paiement) afin de pouvoir réessayer en toute sécurité une requête après une erreur réseau, sans risquer de créer un paiement en double — vérifiez l'existence d'un paiement avec ce clientId avant d'en créer un nouveau si une requête expire.