Getting Started
Status Codes
Understand the HTTP and transaction statuses returned by the Buy Airtime API.
HTTP status codes
| Code | Name | Meaning |
|---|---|---|
| 200 | OK | Request was accepted or completed successfully. |
| 400 | Bad Request | Request syntax or required data is invalid. |
| 401 | Unauthorized | Authentication is missing, invalid or expired. |
| 403 | Forbidden | Credentials are valid but the operation is not permitted. |
| 404 | Not Found | The requested resource or transaction does not exist. |
| 409 | Conflict | Request conflicts with the current state, including an idempotency payload mismatch. |
| 422 | Unprocessable Entity | Request is structurally valid but validation fails. |
| 429 | Too Many Requests | Rate limit has been exceeded. Respect Retry-After. |
| 500 | Internal Server Error | Unexpected server-side failure. |
| 502 | Bad Gateway | Upstream provider communication failed or returned an invalid response. |
| 503 | Service Unavailable | Service is temporarily unavailable. |
Transaction statuses
HTTP 200 does not necessarily mean airtime has already been delivered. A transaction may continue processing after the initial request.
| Status | Meaning |
|---|---|
| pending | Transaction has been created and is waiting to be processed. |
| processing | Transaction is currently being sent to or confirmed by the provider. |
| completed | Airtime delivery completed successfully. |
| failed | Transaction could not be completed. |
Error response
JSON
{{"error":"invalid_request","message":"The amount must be greater than zero."}}Recommended handling
- Handle HTTP status first, then inspect the response body.
- Do not treat every HTTP 200 as final transaction delivery.
- For 429, follow the rate-limit guidance.
- For timeouts, retry the same intended transaction with the same idempotency key.
- Use transaction status or webhooks to determine the final outcome.
Backend contract note
The HTTP and transaction status pages are being designed before backend implementation. The exact error-code names and final transaction state machine should be kept synchronized when the API server is implemented.