Errors and limits
Every error has an HTTP status and a stable machine-readable code. Branch on the code, show the message to humans.
Error format
json
{
"error": {
"code": "refund_exceeds_paid",
"message": "Only 50000 (minor units) is still refundable on this payment."
}
}Messages are for people and may be reworded. Codes will not change.
Error codes
| HTTP | Code | Meaning and what to do |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed. The message names it. |
| 400 | idempotency_key_required | Add an Idempotency-Key header to the POST. |
| 400 | invalid_idempotency_key | The key is longer than 255 characters. |
| 400 | invalid_test_card | Sandbox only: use one of the listed test cards. |
| 401 | missing_api_key | Send Authorization: Bearer <key>. |
| 401 | invalid_api_key | The key is wrong, or was revoked. |
| 401 | missing_merchant_id | Send the X-Merchant-Id header. |
| 401 | invalid_merchant_id | The merchant ID does not belong to that key. |
| 403 | wrong_environment | A sandbox key on the live API, or the reverse. |
| 403 | merchant_suspended | The merchant or developer account is suspended. Contact Payder. |
| 403 | live_not_enabled | Live access is not enabled for your account yet. |
| 404 | not_found | No checkout, refund or payout with that reference. |
| 404 | payment_not_found | No payment with that paymentReference. |
| 409 | duplicate_reference | That reference is already used by a different request. |
| 409 | idempotency_key_reused | That Idempotency-Key was used with a different body. |
| 409 | request_in_progress | The first request with that key is still running. Retry shortly. |
| 409 | payment_not_paid | Only a successful payment can be refunded. |
| 422 | refund_exceeds_paid | The refund is more than what is still refundable. |
| 422 | insufficient_balance | Live payout is more than your available balance. |
| 422 | unsupported_bank | Payder could not match that bank name. |
| 429 | rate_limited | Slow down. Wait for the Retry-After seconds. |
| 5xx | varies | Something went wrong on our side. Retry with the same Idempotency-Key. |
Retrying safely
- 429 and 5xx: retry with exponential backoff, using the same
Idempotency-Key. You will never create a duplicate. - 4xx: do not retry unchanged. Fix the request first.
- Timeouts: you do not know if it worked. Retry with the same key, or GET the object by your reference.
Limits
| Limit | Value |
|---|---|
| Request rate | 120 requests per minute per API key |
| Checkout amount | ₦1 (100 kobo) to ₦20,000,000 |
| Payout amount | ₦100 (10,000 kobo) to ₦20,000,000 |
| Reference | Up to 100 characters: letters, digits and . _ : - |
| Metadata | Up to 4 KB |
| Idempotency key | Up to 255 characters, remembered for 24 hours |
| Checkout lifetime | 24 hours, then it expires |
| Active API keys | 10 per merchant |