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

# Errors

> The error envelope, status codes, and failure shapes.

Aquila returns errors as JSON with a stable shape:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "error": "Validation failed",
  "details": { "target": ["Required"] }
}
```

* `error` — a short human-readable message.
* `details` — optional. Present on request validation failures. The shape
  mirrors the failing fields.

## Status codes

| Status | Meaning                                                                     |
| ------ | --------------------------------------------------------------------------- |
| `200`  | Success. Some idempotent creates return `200` with the existing row.        |
| `201`  | Created. The body carries the new row.                                      |
| `202`  | Accepted. Aquila queued the work. Poll or subscribe for the result.         |
| `400`  | The request failed validation, or the operation is not valid in this state. |
| `401`  | No valid session cookie or API key.                                         |
| `403`  | Your email is not verified, or your role lacks access.                      |
| `404`  | No such id for this user. Aquila never confirms foreign ids.                |
| `405`  | Method not supported. Some resources accept PATCH but not PUT.              |
| `409`  | Conflict. The resource is busy or the operation already ran.                |
| `429`  | Rate limit exceeded. See [Rate limits](/rate-limits).                       |
| `500`  | Server fault. Retry with backoff.                                           |
| `502`  | An upstream hand-off failed. Example: opening a Hackbot session for a lead. |

## Async operations

Scan starts, bulk deletions, and report generation return `202`. The response
names the job or resource. Poll the matching `GET` endpoint, or watch the
dashboard, until the work completes.

## Streaming responses

The AI generation endpoints stream NDJSON frames instead of one JSON body.
Each line is a frame of type `chunk`, `final`, or `error`. Read the line
until the stream closes. Three of these endpoints speak WebSocket instead. The
endpoint descriptions in the API reference mark them.