Errors
Errors share one shape:
{ "code": "INSUFFICIENT_FUNDS", "message": "Insufficient balance" }
Switch on code; it never changes. message is readable and may be
reworded. Some errors carry details, for example minAmountMinor with
AMOUNT_TOO_LOW.
Access
| HTTP | code | Meaning |
|---|---|---|
| 401 | UNAUTHENTICATED | Missing, unknown or revoked API key |
| 403 | BUSINESS_NOT_ACTIVE | Your business account is suspended or closed |
| 403 | IP_NOT_ALLOWED | Request from an address not on your allowlist |
| 429 | TOO_MANY_REQUESTS | Over 120 requests a minute for this key |
Request
| HTTP | code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | A field is missing or malformed; message says which |
| 400 | IDEMPOTENCY_KEY_REQUIRED | POST /bills without a valid Idempotency-Key |
| 409 | IDEMPOTENCY_KEY_REUSED | That key was used for a different payment |
| 400 | PHONE_INVALID | Not a Nigerian mobile number |
| 400 | IDENTIFIER_INVALID | Not a valid smartcard or meter number |
| 400 | AMOUNT_REQUIRED | Airtime and electricity need amountMinor |
| 400 | AMOUNT_INVALID | Amount must be whole naira |
| 400 | AMOUNT_MISMATCH | amountMinor differs from the plan's price |
| 400 | PRODUCT_REQUIRED | Data and cable TV need productCode |
| 422 | PRODUCT_UNKNOWN | No such plan for that biller |
| 422 | BILLER_UNKNOWN | No such biller for that bill type |
| 404 | NOT_FOUND | No such payment on your account |
Payment
| HTTP | code | Meaning |
|---|---|---|
| 422 | INSUFFICIENT_FUNDS | The wallet cannot cover totalMinor; nothing was charged |
| 422 | BILL_VALIDATION_FAILED | The biller did not recognise the number |
| 422 | AMOUNT_TOO_LOW / AMOUNT_TOO_HIGH | Outside what the biller sells; see details |
| 422 | QUOTE_REJECTED / BILL_REJECTED | The biller refused the request |
A biller can also refuse a payment after you sent it. Then the payment
is FAILED (in the response or by webhook) and your wallet is refunded.
Availability
| HTTP | code | Meaning |
|---|---|---|
| 503 | FEATURE_UNAVAILABLE | This bill type is paused; message says why |
| 503 | BILLS_TEMPORARILY_UNAVAILABLE / PROVIDER_UNAVAILABLE | Try again shortly |
| 500 | INTERNAL_ERROR | Something went wrong on our side |
On a 5xx or a timeout during POST /bills, retry with the same
Idempotency-Key. Never use a new key until you know the first attempt
was not created (GET /bills/by-key/{key} returns 404).