Erreurs et idempotence | Konnect Developers

Codes HTTP

Code	Signification	Que faire
`200`, `201`	Succès	Continuer.
`400`	Requête invalide (champ manquant, format)	Corriger la requête ; ne pas réessayer telle quelle.
`401`	Clé API absente ou invalide	Vérifier la clé et l'environnement (sandbox ou production).
`404`	Ressource introuvable	Vérifier la référence ; en v2, le `paymentRef` a 24 caractères hexadécimaux.
`409`	Requête identique encore en cours (v3)	Attendre une seconde, puis rejouer avec la même `Idempotency-Key`.
`422`	Règle métier refusée	Lire le message ; corriger les données.
`429`	Trop de requêtes	Réessayer après le délai `Retry-After`.
`5xx`	Incident côté Konnect ou prestataire	Réessayer avec un délai croissant (par exemple 1, 2, 4, 8 secondes).

Format des erreurs

v2, identique à la plateforme actuelle :

{ "errors": [{ "msg": "amount must be between 100 and 30000000", "param": "amount" }] }

pour une erreur de validation, et { "message": "Payment not found" } pour une erreur métier.

v3 : un code stable, lisible par votre programme, et un message lisible par un humain.

{ "error": "idempotency_key_reused", "message": "This key was used with another request body." }

Branchez votre code sur error, jamais sur message (qui peut changer).

Idempotence (v3)

Un réseau coupé au mauvais moment laisse une question : le paiement a-t-il été créé ? Avec l'en-tête Idempotency-Key, vous pouvez rejouer la même requête sans risque de doublon.

Générez une clé unique par opération métier (par exemple un UUID v4 stocké avec la commande), de 1 à 255 caractères ASCII visibles.
Rejouer la même clé avec le même corps renvoie la réponse d'origine, avec l'en-tête Idempotent-Replayed: true.
La même clé avec un autre corps, ou sur une autre route, renvoie 422 idempotency_key_reused.
Une rejoue pendant que la première requête est encore traitée renvoie 409 idempotency_request_in_progress.
Une clé mal formée renvoie 400 invalid_idempotency_key.
Les réponses sont conservées 24 heures. Une requête qui a échoué n'est pas conservée : vous pouvez la rejouer avec la même clé.

curl -X POST "$KONNECT_API_URL/payments" \
  -H "x-api-key: $KONNECT_API_KEY" \
  -H "Idempotency-Key: 3f1c9a52-2d4e-4b8f-9a60-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 120000, "currency": "TND", "orderId": "order-1001" }'

Route de paiement v3 à venir

POST /payments illustre la création de paiement v3 prévue en phase 2. L'en-tête x-api-key (clés kpk_...) et le mécanisme d'idempotence sont déjà en place : voir la référence v3.

Réessayer sans risque en v2

La v2 n'accepte pas Idempotency-Key. Pour éviter un double paiement :

Ne rejouez pas init-payment après un délai dépassé sans savoir s'il a abouti : créez plutôt un nouveau paiement pour une nouvelle tentative de l'acheteur, et gardez orderId identique.
Livrez une commande une seule fois, en vérifiant dans votre base qu'elle n'est pas déjà payée avant de la marquer payée.