> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/reference/introduction/errors/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# Errors

Ada's API uses conventional HTTP response codes to indicate the success or failure of API requests. In general:

* Codes in the `2xx` range indicate success
* Codes in the `4xx` range indicate errors caused by the request
* Codes in the `5xx` range indicate errors on our servers

## HTTP status code summary

| Status Code | Error Type            | Description                                                      |
| ----------- | --------------------- | ---------------------------------------------------------------- |
| 400         | Bad Request           | The request was malformed or contained invalid parameters        |
| 401         | Unauthorized          | Authentication credentials were missing or invalid               |
| 403         | Authorization Error   | The authenticated user lacks permission to access the resource   |
| 404         | Not Found             | The requested resource doesn't exist                             |
| 409         | Duplicate Resource    | A resource with the same identifier already exists               |
| 413         | Content Too Large     | The request payload exceeds size limits                          |
| 422         | Unprocessable Content | The request syntax was valid but the content cannot be processed |
| 429         | Too Many Requests     | Rate limit exceeded - too many requests in a given time period   |
| 500         | Internal Server Error | Something went wrong on our servers                              |

## Error response format

All error responses follow this format:

```json
{
  "errors": [
    {
      "type": "error_type",
      "message": "Human readable message",
      "details": "Optional, additional error details"
    }
  ]
}
```

## Validation errors

For validation errors (`"type": "validation_error"`), `details` is always a list of error objects, or `null` when there is no field-level detail. Each error object contains:

* `parameter`: A JSON path identifying the field that failed validation (for example, `$[0].knowledge_source_id`).
* `location`: Where the parameter was found in the request (for example, `body`).
* `message`: A human-readable description of the problem.

```json
{
  "errors": [
    {
      "type": "validation_error",
      "message": "invalid articles data",
      "details": [
        {
          "parameter": "$[0].knowledge_source_id",
          "location": "body",
          "message": "Knowledge source with id 'bogus_id' does not exist."
        }
      ]
    }
  ]
}
```