Errors - Aquila

Aquila returns errors as JSON with a stable shape:

{
  "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.
`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.