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

# Errors

> Reference this page for HTTP status codes, error response formats, and troubleshooting guidance for the Chameleon API.

The Chameleon API is robust with 99.99% uptime and extensive monitoring. In case you are facing any issues, you can check our [Status Page](https://status.chameleon.io).

***

## Error response format

All error responses from the Chameleon API follow a consistent JSON format:

```json theme={null}
{
  "code": 422,
  "messages": ["Unprocessable: A description of what went wrong"]
}
```

| Field      | Type           | Description                                          |
| ---------- | -------------- | ---------------------------------------------------- |
| `code`     | integer        | The HTTP status code                                 |
| `messages` | array\<string> | One or more human-readable error messages            |
| `wait`     | integer        | (429 only) Number of seconds to wait before retrying |

***

## Status codes at a glance

| Code  | Meaning               | Common cause                         |
| ----- | --------------------- | ------------------------------------ |
| `200` | OK                    | Request succeeded                    |
| `201` | Created               | Resource was created successfully    |
| `403` | Unauthorized          | Invalid or revoked API token         |
| `404` | Not Found             | Bad URL or resource doesn't exist    |
| `409` | Conflict              | Resource is in an incompatible state |
| `422` | Unprocessable         | Invalid request parameters           |
| `429` | Rate Limited          | Too many requests                    |
| `500` | Internal Server Error | Unexpected server-side error         |
| `503` | Service Unavailable   | Server maintenance or overload       |
| `504` | Gateway Timeout       | Request took too long to process     |

***

<a id="code-403" />

## Status Code 403 — Unauthorized

Account token is not valid or has been revoked.

```json theme={null}
{
  "code": 403,
  "messages": ["Unauthorized: Please check your Chameleon Account Secret"]
}
```

**Troubleshooting:**

* Verify your `X-Account-Secret` header value matches a token from [Settings → Tokens](https://app.chameleon.io/settings/tokens).
* Check that the token hasn't been revoked. You can generate a new one from the dashboard.
* Ensure you're using the **Account Secret** (not the Account Token, which is for the JavaScript snippet).
* Confirm the header name is exactly `X-Account-Secret` (case-sensitive).

***

<a id="code-404" />

## Status Code 404 — Not Found

Endpoint or resource not found.

```json theme={null}
{
  "code": 404,
  "messages": ["Endpoint not found: Please recheck with the API docs https://developers.chameleon.io"]
}
```

**Troubleshooting:**

* Verify the URL was copied correctly. URLs include an environment specifier after the version (e.g., `/v3/edit/tours`, `/v3/analyze/profiles`).
* Check that the resource ID exists and belongs to your account.
* Ensure the base URL is `https://api.chameleon.io` (not a typo or old URL).
* For profile lookups, confirm the `uid` or `email` has been previously identified to Chameleon.

***

<a id="code-409" />

## Status Code 409 — Conflict

The resource is in a state that conflicts with the requested operation.

```json theme={null}
{
  "code": 409,
  "messages": ["Conflict: Please check the preconditions in the API docs https://developers.chameleon.io"]
}
```

**Common scenarios:**

* **Delivery to unpublished Experience** — The Tour or Microsurvey must be published before creating a Delivery. Publish it first via the dashboard or API.
* **Updating a triggered Delivery** — Once a Delivery has been triggered (`at` has a value), it can no longer be modified or deleted.
* **Too many pending Deliveries** — A user has reached the pending Delivery limit (default: 3). Use `delivery_ids_at_limit=drop` to replace the oldest, or delete existing Deliveries first.
* **Import already started** — Once `import_at` is set on an Import, it can't be updated.
* **Search item/group limits exceeded** — HelpBar content limits reached. See [HelpBar limits](/apis/search#limits).

***

<a id="code-422" />

## Status Code 422 — Unprocessable

The request parameters can't be processed as provided.

```json theme={null}
{
  "code": 422,
  "messages": ["Unprocessable: Please check the request parameters with the API docs https://developers.chameleon.io"]
}
```

**Common scenarios:**

* **Invalid timestamp** — A parameter expected as a timestamp can't be parsed. Use ISO 8601 format (e.g., `"2024-01-15T10:30:00Z"`).
* **Missing identifier** — Looking up a User Profile requires at least one of `id`, `uid`, or `email`.
* **Invalid filter expression** — A [segmentation filter](/concepts/filters) has incorrect syntax or unsupported operators.
* **Import property mismatch** — CSV column headers don't match the specified `properties` mapping.
* **Invalid enum value** — A parameter like `kind` or `model_kind` has an unrecognized value.

***

<a id="code-429" />

## Status Code 429 — Rate Limited

You've exceeded the rate limit for concurrent or bucketed requests.

```
X-Ratelimit-Wait: 114
X-Ratelimit-Limit: 2
```

```json theme={null}
{
  "code": 429,
  "messages": ["Rate Limited: Please refer to the API docs https://developers.chameleon.io/concepts/rate-limiting for more information"],
  "wait": 14
}
```

**Troubleshooting:**

* Check the `wait` field in the response body — this tells you how many seconds to wait before retrying.
* Check the `X-Ratelimit-Wait` header for the wait time in seconds.
* Implement exponential backoff: wait the specified time, then retry with increasing delays if still limited.
* Review your concurrency: the Chameleon API limits concurrent requests per endpoint. See [Rate limiting](/concepts/rate-limiting) for per-endpoint limits.
* For bulk operations, consider using batch endpoints (e.g., [bulk tagging](/apis/tags#tags-bulk)) instead of individual requests.

***

<a id="code-500" />

## Status Code 500 — Internal Server Error

An unexpected server-side error occurred.

```json theme={null}
{
  "code": 500,
  "messages": ["Internal server error: Please retry later"]
}
```

**Troubleshooting:**

* This is typically a transient issue. Wait a few seconds and retry.
* If the error persists, check [status.chameleon.io](https://status.chameleon.io) for any ongoing incidents.
* If the problem continues after retrying, [contact support](https://app.chameleon.io/help) with the request details and timestamp.

***

<a id="code-503" />

## Status Code 503 — Service Unavailable

Server not available or backend didn't respond in time. The response may not be JSON depending on the origin.

```json theme={null}
{
  "code": 503,
  "messages": []
}
```

**Troubleshooting:**

* This typically indicates maintenance or temporary unavailability. Check [status.chameleon.io](https://status.chameleon.io).
* Implement retry logic with exponential backoff.
* If you see frequent 503 errors, you may be hitting system-wide rate limits. See [Rate limiting](/concepts/rate-limiting).

***

<a id="code-504" />

## Status Code 504 — Gateway Timeout

An internal operation took too long to complete.

```json theme={null}
{
  "code": 504,
  "messages": ["Internal timeout: An internal operation took too long."]
}
```

**Troubleshooting:**

* The request may have been too complex (e.g., a broad search query or large filter set). Try narrowing your request.
* Retry after a brief delay. If the issue persists, simplify the request parameters.
* For large dataset operations, use [pagination](/concepts/pagination) with smaller `limit` values.