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

# Errors

> HTTP status codes, the error response format, and retry guidance for the Auxia API.

Auxia uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

* Codes in the `2xx` range indicate success.
* Codes in the `4xx` range indicate an error caused by the request, such as a missing required field, an invalid API key, or a reference to a resource that does not exist. Except for `429`, retrying the same request will not succeed.
* Codes in the `5xx` range indicate an error on Auxia's side. These are rare, and are usually safe to retry.

## Error response

Every error response from the API has an `application/json` body with the following attributes.

| Attribute | Type | Description |
| - | - | - |
| `code` | Integer | The HTTP status code of the response. Always the same as the status line. |
| `message` | String | A human-readable description of the error. Messages are for developers and may change; do not parse them or branch on them. |

```json theme={null}
{
  "code": 400,
  "message": "user_id must be set in request"
}
```

Some messages end with a reference ID, such as `Reference A0D3427F89CACF13.F26AB72FAA88C751` or `[ID: 66A1855B08B0DF57.057CA4DCB18714FF; ...]`. Include it when you contact Auxia about a failed request.

## HTTP status code summary

| Code | Name | Description |
| - | - | - |
| 200 | OK | The request succeeded. |
| 400 | Bad Request | The request was invalid, often because a required field is missing, a value is malformed, or the body is not valid JSON. |
| 403 | Forbidden | The API key is missing, invalid, or does not have permission to call this API for this project. Auxia returns `403` for all API key failures; it does not return `401`. |
| 404 | Not Found | The project, or another resource the request refers to, does not exist. Also returned for an unknown API path. |
| 405 | Method Not Allowed | The API was called with an HTTP method other than `POST`. |
| 409 | Conflict | The request conflicts with a resource that already exists, for example a treatment with the same `external_treatment_id`. |
| 413 | Payload Too Large | The request body is larger than 1 MiB, or 16 MiB for Insert Treatment and Update Treatment. |
| 429 | Too Many Requests | The project exceeded the request rate limit for this API. See [Rate limits](#rate-limits). |
| 500 | Internal Server Error | An unexpected error or an internal timeout occurred on Auxia's side. |
| 502 | Bad Gateway | Auxia's load balancer could not get a response from the API. |
| 503 | Service Unavailable | Auxia is temporarily unable to handle the request. |
| 504 | Gateway Timeout | The API gateway did not get a response within its time limit. |

## Server errors

A `500` response has the standard error body:

```json theme={null}
{
  "code": 500,
  "message": "An unexpected error occurred; please contact Auxia for more information. [ID: 66A1855B08B0DF57.057CA4DCB18714FF; MI: 16DBD8420A570FAA; P: auxia-gcp]"
}
```

A timeout inside Auxia also returns `500`, with `error code E4896` in the message.

`503` and `504` responses returned by the API use the same format.

A `5xx` response returned by Auxia's load balancer, rather than by the API itself, has a `text/html` body instead. For example, a `502`:

```html theme={null}
<html><head>
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<title>502 Server Error</title>
</head>
<body text=#000000 bgcolor=#ffffff>
<h1>Error: Server Error</h1>
<h2>The server encountered a temporary error and could not complete your request.<p>Please try again in 30 seconds.</h2>
<h2></h2>
</body></html>
```

Handle server errors by status code, not by body.

## Handling errors

| Code | Retry? | What to do |
| - | - | - |
| 400, 404, 405, 413 | No | Fix the request. The `message` identifies the problem. |
| 403 | No | Check that the API key is correct, is sent in the `x-api-key` header, and has the key type this API requires. |
| 409 | No | The resource already exists. Read it, or update it instead of inserting it. |
| 429 | Yes | Wait for the number of seconds in the `Retry-After` header, then retry. |
| 500 | Yes, if the API is safe to retry | Retry with exponential backoff, a small number of times. If the error persists, contact Auxia with the reference ID. |
| 502, 503, 504 | Yes, if the API is safe to retry | Retry with exponential backoff and jitter. |

When you retry, use exponential backoff with jitter: wait about 1 second before the first retry, double the wait after each attempt, and add a random delay. Cap the number of attempts so that a sustained outage does not multiply your traffic.

### Retry safety

A request that fails with a `5xx` error, or times out on your side, may still have been applied. Before you retry a request that writes data, check whether a duplicate would cause a problem.

| API | Safe to retry | Notes |
| - | - | - |
| [Get Treatments](/api-reference/get-treatments) | Yes | Each call is a new decision with a new `responseId`. Use the treatments from the response you render. |
| [Get Treatment](/api-reference/treatment-management/get-treatment), [Get All Treatments](/api-reference/treatment-management/get-all-treatments), [Get DataFields](/api-reference/treatment-management/get-datafields) | Yes | Read-only. |
| [Insert Surface](/api-reference/treatment-management/insert-surface), [Insert Data Field](/api-reference/treatment-management/insert-data-field) | Yes | Idempotent. Inserting an item that already exists returns the existing item. |
| [Insert Treatment Type](/api-reference/treatment-management/insert-update-treatment-type) | Yes | An identical request returns the existing treatment type. A different request with the same name returns `409`. |
| [Update Treatment Type](/api-reference/treatment-management/insert-update-treatment-type), [Update Treatment](/api-reference/treatment-management/insert-update-treatment) | Yes | Repeating the same update produces the same result. |
| [Insert Treatment](/api-reference/treatment-management/insert-update-treatment) | With `external_treatment_id` | Set `external_treatment_id` so that a retry of an insert that already succeeded returns `409` instead of creating a second treatment. |
| [Log Treatment Interaction](/api-reference/log-treatment-interactions) | With care | Interactions are not deduplicated. A retry of a request that already succeeded may record the interaction twice. |
| [Log Events](/api-reference/log-events) | With `insertId` | Set `insertId` on each event so that retried events can be deduplicated. |

## Rate limits

[Insert Treatment](/api-reference/treatment-management/insert-update-treatment) and [Update Treatment](/api-reference/treatment-management/insert-update-treatment) can be rate-limited per project. When a project exceeds its limit, the API returns `429` with these headers:

| Header | Description |
| - | - |
| `Retry-After` | Seconds to wait before retrying. |
| `X-RateLimit-Limit` | The maximum number of requests per second allowed for the project. |
| `X-RateLimit-Remaining` | The number of requests remaining in the current window. |

## Testing error handling

To test how your integration handles errors, stub the Auxia API in your own test environment and return the status codes and bodies on this page. Auxia does not provide a way to trigger server errors on demand.


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