BILLS PAYMENT

Errors

Common error code values returned across all Bills Payment endpoints.

Use this page to

Look up what a code in an error response means
Decide how to handle each error type in your integration
Understand when it's safe to retry a request

Code	Meaning
`INVALID_REQUEST`	Missing or invalid fields in the request
`UNAUTHORIZED`	Business not found or inactive
`PRODUCT_UNAVAILABLE`	No matching product/network/provider/disco configured
`INSUFFICIENT_BALANCE`	Business wallet balance too low to complete the purchase
`BILL_FAILED`	Provider declined the transaction; wallet is auto-refunded
`PROVIDER_ERROR`	The provider/discovery call failed
`VERIFY_FAILED`	Customer verification call failed

Error shape

{
  "status": "error",
  "code": "INSUFFICIENT_BALANCE",
  "message": "Business wallet balance is too low to complete this transaction."
}

Handling recommendations

Situation	Recommended handling
`INVALID_REQUEST`	Fix the request payload — check required fields and value ranges (e.g. airtime `amount` 50–20,000, electricity `amount` ≥ 2,000)
`UNAUTHORIZED`	Check your access token and business status
`PRODUCT_UNAVAILABLE`	Re-fetch Get Billers / Get Data Plans / Get Cable Plans — the slug or package may be stale
`INSUFFICIENT_BALANCE`	Top up the business wallet before retrying
`BILL_FAILED`	Wallet has already been refunded — safe to retry with a new `reference`, or investigate with the customer
`PROVIDER_ERROR` / `VERIFY_FAILED`	Transient — retry with the same `reference` after a short delay

Note: Retrying any purchase with the same reference never double-charges — you'll get the original transaction back. Only use a new reference when you intend to make a genuinely new purchase.

Questions? Email [email protected]. Also on GitBook.