> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rapidtopup.com.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Reference for HTTP status codes returned by the RapidTopup B2B API, with example error responses for authentication failures, insufficient balance, and validation errors.

## Status Code Reference

| Code | What it means | What to do |
| - | - | - |
| `200` | Request received and processed | Check `data.status` in the response body for the actual outcome |
| `201` | Resource created (e.g. API key generated) | No action needed |
| `400` | Insufficient balance, or the provider rejected the account lookup | Top up your wallet, or verify the account number and service ID |
| `401` | API key is missing, malformed, or revoked | Check your `Authorization: Bearer ...` header format |
| `403` | Key is valid but the account is suspended or not upgraded | Contact support or upgrade your account to Top User |
| `404` | Transaction reference or resource not found | Double-check the reference value you submitted |
| `422` | Validation failed — a required field is missing or wrongly formatted | Read the `errors` object in the response for the exact field |
| `429` | Rate limit exceeded (100 requests per minute) | Wait and retry with exponential backoff — do not hammer immediately |
| `503` | Upstream carrier or utility provider is temporarily unavailable | Retry after a short delay |

***

## Common Error Examples

> [accordion] 401 — Missing or Invalid API Key
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Unauthorized. Invalid or missing API key format."
> }
> ```
>
> **Fix:** Ensure your `Authorization` header is set to `Bearer rtu_live_sk_...` or `Bearer rtu_test_sk_...`

> [accordion] 403 — Account Suspended
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Unauthorized. Account is suspended."
> }
> ```
>
> **Fix:** Contact support at [support@rapidtopup.com.ng](mailto:support@rapidtopup.com.ng)

> [accordion] 400 — Insufficient Wallet Balance
>
> ```json theme={null}
> {
>   "error": "Insufficient wallet balance."
> }
> ```
>
> **Fix:** Top up your RapidTopup reseller wallet before retrying the purchase.

> [accordion] 400 — Insufficient Sandbox Wallet Balance
>
> ```json theme={null}
> {
>   "status": "error",
>   "environment": "sandbox",
>   "error": "Insufficient sandbox wallet balance. Please click \"Top Up Test Balance\" in your Developer Portal."
> }
> ```
>
> **Fix:** Click **"Top Up Test Balance"** in your Developer Dashboard to instantly refill your sandbox test balance back to ₦500,000.00.

> [accordion] 422 — Validation Error
>
> ```json theme={null}
> {
>   "message": "The phone number field must be 11 digits.",
>   "errors": {
>     "phone_number": ["The phone number field must be 11 digits."]
>   }
> }
> ```
>
> **Fix:** Check all required fields and their formats in the [endpoint docs](https://docs.rapidtopup.com.ng/api-reference/purchase.md).

> [accordion] 400 — Verification Failure
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Could not verify meter number. Please check the meter number and meter type."
> }
> ```
>
> **Fix:** Verify the account number and `service_id` are correct before calling `/purchase`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.