Errors and idempotency | Konnect Developers

HTTP codes

Code	Meaning	What to do
`200`, `201`	Success	Carry on.
`400`	Invalid request (missing field, format)	Fix the request; do not retry it as is.
`401`	Missing or wrong API key	Check the key and the environment (sandbox or production).
`404`	Resource not found	Check the reference; in v2, `paymentRef` has 24 hexadecimal characters.
`409`	Same request still in progress (v3)	Wait a second, then replay with the same `Idempotency-Key`.
`422`	Business rule refused	Read the message; fix the data.
`429`	Too many requests	Retry after the `Retry-After` delay.
`5xx`	Incident at Konnect or at a provider	Retry with a growing delay (for example 1, 2, 4, 8 seconds).

Error format

v2, the same as the current platform:

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

for a validation error, and { "message": "Payment not found" } for a business error.

v3: a stable code for your program and a message for a human.

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

Branch your code on error, never on message (which can change).

Idempotency (v3)

A network cut at the wrong time leaves a question: was the payment created? With the Idempotency-Key header you can replay the same request without risking a duplicate.

Generate one key per business operation (for example a UUID v4 stored with the order), 1 to 255 visible ASCII characters.
Replaying the same key with the same body returns the original response, with the header Idempotent-Replayed: true.
The same key with another body, or on another route, returns 422 idempotency_key_reused.
A replay while the first request is still running returns 409 idempotency_request_in_progress.
A malformed key returns 400 invalid_idempotency_key.
Responses are kept for 24 hours. A failed request is not kept: you can replay it with the same key.

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" }'

v3 payment route to come

POST /payments shows the v3 payment creation planned for phase 2. The x-api-key header (kpk_... keys) and the idempotency mechanism are already in place: see the v3 reference.

Retrying safely in v2

v2 does not accept Idempotency-Key. To avoid a double payment:

Do not replay init-payment after a timeout without knowing whether it went through: create a new payment for a new attempt of the buyer instead, and keep the same orderId.
Deliver an order once, by checking in your database that it is not already paid before marking it paid.