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

# Errors

> Troubleshoot problems with this comprehensive breakdown of all error codes

Troubleshoot problems with this comprehensive breakdown of all error codes.

## Error schema

We use standard HTTP response codes for success and failure notifications. All errors return a consistent format:

```json theme={"theme":"vesper"}
{
  "message": "Human-readable error description",
  "statusCode": 400,
  "name": "validation_error"
}
```

Use the `name` field for programmatic error handling in your SDK or application.

## Error codes

### `validation_error`

* **Status:** 400
* **Message:** Varies. Describes which field failed validation and why.
* **Suggested action:** Check the `message` field for details. Common causes: missing required fields (`userId`, `email` for identify; `userId`, `event` for track), invalid email format, invalid URL in `avatar`, or event name containing spaces.

### `invalid_write_key`

* **Status:** 401
* **Message:** Missing or invalid Project Token.
* **Suggested action:** Include the `Authorization: Basic rk-xxxxxxxxx` header with a valid [Project Token](/docs/guides/authentication). Ensure the token starts with `rk-` and has not been revoked.

### `not_found`

* **Status:** 404
* **Message:** User not found, please identify the user first using the /identify endpoint.
* **Suggested action:** Call [POST /identify](/docs/api-reference/identify/identify-a-user) before [POST /track](/docs/api-reference/track/track-an-event). Events can only be recorded for users that have been identified.

### `rate_limit_exceeded`

* **Status:** 429
* **Message:** Too many requests. Please limit the number of requests per second.
* **Suggested action:** Reduce the rate of API requests. Consider batching events or introducing a queue. If you need higher limits, contact support.

### `application_error`

* **Status:** 500
* **Message:** An unexpected error occurred, please try again later.
* **Suggested action:** Retry the request. If the error persists, check our status page or contact support.