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

# Errors

> Every error has a code, a message and details

Errors use the same envelope:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some fields of the payment are missing or invalid.",
    "details": {
      "phone_number": "Required: the mobile money number with the country code, digits only, for example 237670000000.",
      "amount": "Whole amounts only for this operator (decimals: 0)."
    }
  },
  "meta": { "request_id": "a4f8e2c1b3d97056", "timestamp": "2026-10-29T10:00:00+00:00", "mode": "live" }
}
```

`details` explains **each** refused field: show it to your developers, map it to your own form.

| HTTP | `code` | When | What to do |
| - | - | - | - |
| `401` | `AUTHENTICATION_REQUIRED` / `AUTHENTICATION_FAILED` | Missing key / wrong key | Check the `Authorization` header and the key mode |
| `403` | `IP_NOT_ALLOWED` | The call does not come from an allowed IP address | Add the IP of your server in your dashboard |
| `403` | `ACCOUNT_RESTRICTED` | Your account is restricted | Contact support |
| `403` | `FORBIDDEN` | The service is not `active` (live mode) | Wait for the review, or enable the service |
| `404` | `RESOURCE_NOT_FOUND` | Unknown service or payment code | Check the code and the key mode (test or live) |
| `422` | `VALIDATION_ERROR` | A field is missing or invalid | Read `details` |
| `422` | `COUNTRY_NOT_SUPPORTED` | The country is not available for your account | Offer another payment method |
| `429` | `RATE_LIMIT_EXCEEDED` | Too many requests | Slow down, cache the countries |
| `503` | `OPERATION_FAILED` | The operator is closed for collections (`details.failure_code: operator_unavailable`) | Offer another operator |

Keep the `meta.request_id` of a failed call: it lets our support find it in seconds.


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