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

# Errors

> HTTP status codes, error response format, and how to handle API errors.

The Ayliea API uses standard HTTP status codes and returns errors in a consistent JSON format.

## Error format

All error responses return a JSON object with a single `error` field containing a human-readable message:

```json theme={null}
{
  "error": "Human-readable error description"
}
```

Error messages are intentionally general and do not expose internal implementation details.

## Status codes

| Code  | Meaning               | When it happens                                                                 |
| ----- | --------------------- | ------------------------------------------------------------------------------- |
| `200` | OK                    | Request succeeded                                                               |
| `400` | Bad request           | Invalid query parameters (e.g., `limit` out of range)                           |
| `401` | Unauthorized          | Missing or invalid `X-API-Key` header                                           |
| `403` | Forbidden             | API key lacks the required scope, or organization is not on the Enterprise tier |
| `404` | Not found             | Requested resource does not exist                                               |
| `409` | Conflict              | Duplicate resource (e.g., maximum API keys reached)                             |
| `429` | Too many requests     | [Rate limit](/api-reference/rate-limiting) exceeded                             |
| `500` | Internal server error | Unexpected server-side failure                                                  |

## Example error responses

<Tabs>
  <Tab title="401 Unauthorized">
    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```
  </Tab>

  <Tab title="403 Forbidden">
    ```json theme={null}
    {
      "error": "API key does not have the 'scores:read' scope"
    }
    ```
  </Tab>

  <Tab title="400 Bad request">
    ```json theme={null}
    {
      "error": "limit must be an integer between 1 and 100"
    }
    ```
  </Tab>

  <Tab title="429 Rate limited">
    ```json theme={null}
    {
      "error": "Too many requests. Please try again later."
    }
    ```
  </Tab>

  <Tab title="500 Server error">
    ```json theme={null}
    {
      "error": "Failed to query scores"
    }
    ```
  </Tab>
</Tabs>

## Handling errors

**`4xx` errors** indicate a problem with your request. Check the error message, fix the issue, and retry.

**`429` errors** mean you have been rate limited. Wait for the `Retry-After` period and retry. See [Rate limiting](/api-reference/rate-limiting) for details.

**`500` errors** indicate a server-side problem. These are safe to retry with exponential backoff. If `500` errors persist, contact [support@ayliea.com](mailto:support@ayliea.com).