> ## 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.

# Authmatech API Errors & Response Envelope

> The Authmatech response envelope, every HTTP status code and error code, retry strategy, and a debugging checklist to resolve issues faster.

Every Authmatech API call — success or failure — returns the same JSON envelope. Understanding it, and the status codes that accompany it, lets you build resilient integrations and resolve issues quickly.

## The response envelope

Authmatech does **not** return a bare `{ error: ... }` object. Instead, every response is wrapped consistently:

```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
}
```

| Field                   | Type           | Description                                               |
| ----------------------- | -------------- | --------------------------------------------------------- |
| `success`               | boolean        | `true` if the operation succeeded                         |
| `messages`              | array          | One or more messages describing the outcome               |
| `messages[].type`       | string         | `SUCCESS`, `FAILURE`, `INFO`, or `WARNING`                |
| `messages[].code`       | string \| null | A machine-readable error code (see below)                 |
| `messages[].message`    | string \| null | A human-readable explanation                              |
| `messages[].httpStatus` | string         | The status name mirrored in the body (e.g. `BAD_REQUEST`) |
| `messages[].technical`  | boolean        | `true` for internal/technical messages                    |
| `messages[].arguments`  | object \| null | Optional structured context                               |
| `data`                  | object \| null | The result payload on success; `null` on failure          |

<Warning>
  A negative business outcome is **not** an error. A verification that returns `{"success": true, "data": {"validNumber": false}}` is a successful `200` call with a negative verdict. Branch your logic on `data`; reserve error handling for `success: false` and non‑`200` status codes.
</Warning>

## HTTP status codes

| Status | Name                  | Common cause                                                                                         | How to resolve                                                                |
| ------ | --------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `200`  | OK                    | Request succeeded (the verdict may still be negative)                                                | Inspect `data` for the outcome                                                |
| `201`  | Created               | A resource was created (onboarding, key generation)                                                  | Read the new resource from `data`                                             |
| `204`  | No Content            | Success with no body                                                                                 | No action needed                                                              |
| `400`  | Bad Request           | Missing/invalid fields, malformed JSON, **product not enabled**, or **insufficient/expired balance** | Check the `messages[].message`, your payload, product enablement, and balance |
| `401`  | Unauthorized          | `X-API-KEY` or `X-CLIENT-ID` missing or invalid                                                      | Confirm both headers are present and correct                                  |
| `404`  | Not Found             | The resource id or path does not exist                                                               | Verify the id and endpoint path                                               |
| `500`  | Internal Server Error | An unexpected error on the platform                                                                  | Retry with backoff; if it persists, contact support                           |

<Note>
  Validation, product-enablement, and balance problems all surface as `400 Bad Request` with a descriptive `message`. Always read `messages[].message` rather than relying on the status code alone.
</Note>

## Error codes

The `code` field carries a stable, machine-readable identifier you can branch on. Common values include:

| Code                      | Meaning                               |
| ------------------------- | ------------------------------------- |
| `resource_not_found`      | The requested resource does not exist |
| `resource_already_exists` | A conflicting resource already exists |
| `INVALID_MOBILE_NUMBER`   | The mobile number failed validation   |
| `internal_server_error`   | An unexpected server error occurred   |

Authentication failures are returned as `401` and may not carry a `code` — treat any `401` as "fix the `X-API-KEY` / `X-CLIENT-ID` headers."

## Phone number format

Submit mobile numbers in **E.164 format**: a leading `+`, the full country code (no leading zero), and the subscriber number with no spaces, dashes, or parentheses.

**Valid**

```
+962791234567   ← Jordan
+971501234567   ← United Arab Emirates
+966512345678   ← Saudi Arabia
```

**Invalid**

```
0791234567      ← missing country code
+962 79 123 4567 ← contains spaces
+962-79-1234567  ← contains dashes
```

## Retry strategy

### Retryable

`429 Too Many Requests` and `500 Internal Server Error` are safe to retry. Use **exponential backoff**:

1. Wait \~1 s after the first failure.
2. Double the wait each time: 2 s → 4 s → 8 s …
3. Cap retries (e.g. 5 attempts) and the maximum wait (e.g. 60 s).
4. Add small random **jitter** (±100 ms) so clients don't retry in lockstep.

See [Rate limits](/api/rate-limits) for guidance on `429`.

### Non-retryable

`400`, `401`, and `404` reflect problems in the request itself. Retrying unchanged returns the same result — read `messages[].message` and fix the cause first.

## Debugging checklist

**Authentication (`401`)**

* Are both `X-API-KEY` and `X-CLIENT-ID` present on every request?
* Did you copy the API key without trailing whitespace or quotes?
* Are you using the right credentials for the environment (sandbox vs. production)?

**Request body (`400`)**

* Is `Content-Type: application/json` set and does the JSON parse cleanly?
* Are all required fields present for the endpoint?
* Are mobile numbers in E.164 format?
* Is the **product enabled** and the **balance sufficient and unexpired**?

**Not found (`404`)**

* Is the resource id correct and from the same environment?

## Getting help

If you're still stuck after the checklist, contact [connect@authmatech.com](mailto:connect@authmatech.com) (Sun–Thu, 09:00–18:00 Amman time). To speed up resolution, include:

1. The HTTP status and the `messages[].code` / `messages[].message` from the response.
2. The request URL and method.
3. The request body (redact your API key).
4. The full response body.
5. The approximate time of the error, with timezone.