Skip to main content

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​

HTTPcodeMeaning
401UNAUTHENTICATEDMissing, unknown or revoked API key
403BUSINESS_NOT_ACTIVEYour business account is suspended or closed
403IP_NOT_ALLOWEDRequest from an address not on your allowlist
429TOO_MANY_REQUESTSOver 120 requests a minute for this key

Request​

HTTPcodeMeaning
400BAD_REQUESTA field is missing or malformed; message says which
400IDEMPOTENCY_KEY_REQUIREDPOST /bills without a valid Idempotency-Key
409IDEMPOTENCY_KEY_REUSEDThat key was used for a different payment
400PHONE_INVALIDNot a Nigerian mobile number
400IDENTIFIER_INVALIDNot a valid smartcard or meter number
400AMOUNT_REQUIREDAirtime and electricity need amountMinor
400AMOUNT_INVALIDAmount must be whole naira
400AMOUNT_MISMATCHamountMinor differs from the plan's price
400PRODUCT_REQUIREDData and cable TV need productCode
422PRODUCT_UNKNOWNNo such plan for that biller
422BILLER_UNKNOWNNo such biller for that bill type
404NOT_FOUNDNo such payment on your account

Payment​

HTTPcodeMeaning
422INSUFFICIENT_FUNDSThe wallet cannot cover totalMinor; nothing was charged
422BILL_VALIDATION_FAILEDThe biller did not recognise the number
422AMOUNT_TOO_LOW / AMOUNT_TOO_HIGHOutside what the biller sells; see details
422QUOTE_REJECTED / BILL_REJECTEDThe 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​

HTTPcodeMeaning
503FEATURE_UNAVAILABLEThis bill type is paused; message says why
503BILLS_TEMPORARILY_UNAVAILABLE / PROVIDER_UNAVAILABLETry again shortly
500INTERNAL_ERRORSomething 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).