Errors

This section covers how to handle errors gracefully.

Error Handling

All errors follow a consistent JSON format:

JSON

{
  "error": "Human-readable error description"
}

Code	Meaning
200	Request successful
201	Resource created / transaction initiated
400	Bad request — invalid input or business rule failure
401	Unauthenticated — invalid or missing API key
403	Forbidden — account lacks developer privileges
404	Resource not found
500	Internal server error — retry or contact support

Error	Cause & Fix
`Insufficient balance`	Fund your wallet before retrying
`Airtime service is inactive`	The selected network is currently offline
`Invalid or expired promo code`	The promo code has expired or doesn't exist
`Developer profile not found`	Your account is not yet upgraded to developer
`Unsupported service type`	`service_type` value is not recognized
`Missing required fields`	One of `service_type`, `beneficiary`, `amount` is absent

Rate Limit: 300 requests/minute per API key (subject to change).
Always check wallet balance via GET /profile/ before bulk operations.
Store reference values from your purchase requests — use them to reconcile transactions if a network error occurs before the response is received.
Rotate API keys periodically. Update your configuration immediately after regeneration.
Set up webhooks to receive asynchronous updates instead of constantly polling GET /verify/{reference}/.