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

# Errors

> Status codes the API returns and what to do about them.

Errors come back as JSON with a `detail` field:

```json theme={null}
{ "detail": "invalid or missing X-API-Key" }
```

| Status | `detail` | What it means | What to do |
| - | - | - | - |
| `401` | `invalid or missing X-API-Key` | The key header is missing, or the key is wrong or revoked. | Check your key. |
| `403` | (an HTML page) | The request was blocked before it reached the API, almost always because of a missing or default `User-Agent`. | Send a real `User-Agent` header. |
| `413` | `max 10000 numbers per batch` | The batch has more than 10,000 numbers. | Split it. Batches of 2,000 or fewer work best. |
| `422` | A list of field errors | The request is malformed: no `number` parameter, or a body that isn't `{"numbers": [...]}`. | Fix the request. |
| `503` | `key store unreachable, try again shortly` | Your key couldn't be checked for a moment. | Retry after a few seconds. |
| `503` | `server auth not configured` | The service isn't ready. | Retry later. |

## A bad number isn't an error

A number that isn't a valid +1 number still returns `200`, with `verdict: "invalid"` and the reason:

```json theme={null}
{ "phone": "+44 20 7946 0000", "phone_valid": false, "e164": null, "verdict": "invalid", "reasons": ["not a valid NANP number (format)"] }
```

In a batch, one bad number never fails the whole call.

## Retrying

Retry `503` and network errors with exponential backoff (for example 1s, 2s, 4s). Don't retry `401`, `413` or `422` without changing the request.


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