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

# API Errors & Status Codes

> Quick reference for Authmatech API error handling: the response envelope, HTTP status codes, machine-readable error codes, and which errors are retryable.

Every Authmatech response uses the same envelope. This page is a concise reference; for retry strategy and a debugging checklist, see the full [Errors & responses](/errors) guide.

## Envelope

```json theme={null}
{
  "success": false,
  "messages": [
    { "type": "FAILURE", "code": "resource_not_found", "message": "Client not found.", "httpStatus": "NOT_FOUND", "technical": false, "arguments": null }
  ],
  "data": null
}
```

Read results from `data`. Treat `success: false` or a non‑`200` status as an error.

## Status codes

| Status | Meaning                                                         | Retryable     |
| ------ | --------------------------------------------------------------- | ------------- |
| `200`  | OK (verdict may still be negative)                              | —             |
| `201`  | Created                                                         | —             |
| `204`  | No Content                                                      | —             |
| `400`  | Bad Request — validation, product not enabled, or balance issue | No            |
| `401`  | Unauthorized — bad/missing `X-API-KEY` or `X-CLIENT-ID`         | No            |
| `404`  | Not Found                                                       | No            |
| `429`  | Too Many Requests                                               | Yes (backoff) |
| `500`  | Internal Server Error                                           | Yes (backoff) |

## Error codes

| Code                      | Meaning                             |
| ------------------------- | ----------------------------------- |
| `resource_not_found`      | The resource does not exist         |
| `resource_already_exists` | A conflicting resource exists       |
| `INVALID_MOBILE_NUMBER`   | The mobile number failed validation |
| `internal_server_error`   | Unexpected server error             |

<Warning>
  A `200` with `data.validNumber: false` (or a `BLOCK` decision) is a successful call with a negative business outcome — not an error. Branch on `data`, not just the status code.
</Warning>

See [Errors & responses](/errors) for retry strategy, E.164 rules, and the debugging checklist, and [Rate limits](/api/rate-limits) for `429` handling.