Errors and idempotency
Errors come back with an HTTP status and a code you can act on.
{
"error": {
"code": "insufficient_balance",
"message": "Your available balance is ₦12,000.00; this needs ₦18,510.75.",
"request_id": "req_…"
}
}| Status | Codes |
|---|---|
| 401 | unauthenticated: no key, or a wrong one |
| 402 | insufficient_balance |
| 403 | forbidden, ip_not_allowed, not_live, …_not_enabled for a product not switched on yet, and limit_exceeded when a live checkout would pass your monthly limit (see GET /v1/business) |
| 404 | not_found |
| 409 | duplicate_reference, idempotency_conflict, rate_changed, not_settled, already_refunded, invalid_transition |
| 422 | invalid_input (with details), name_mismatch, amount_too_small, amount_too_large |
| 429 | rate_limited: slow down and retry |
| 502, 503 | provider_refused, not_configured: our payment partner said no or is unavailable |
Idempotency
Send an Idempotency-Key header (up to 255 characters) with any POST. If you send the same request with the same key again, you get the first answer back and nothing happens twice. The same key with a different body gets 409 idempotency_conflict. Use one per order or per payment, such as your order number.
Many objects also take your own reference: a second one with the same reference is refused or returns the first.
paygent