Errors

Every refusal the API makes — from the middleware, from a route handler, or from the schema validator — comes back as JSON with a stable, machine-readable identifier. You branch on that identifier. You never branch on the prose.

The envelope

{
  "error": "ticket_not_found",
  "message": "ticket not found",
  "detail": "ticket not found"
}

Some refusals add fields before those three. They are the machine-readable version of whatever the message says in words:

What each status means here

The three denial codes are used precisely, and the distinction is deliberate:

404 never distinguishes "gone" from "not yours." Existence is not disclosed across a workspace boundary, because a 403 would confirm the id is real. If an id you believe in returns 404, check which workspace your credential belongs to first.

Schema validation is shaped differently

A 422 from the validator is the one case where detail is an array, and where error is always the generic validation_error rather than something specific:

curl -sk -X POST https://api.localhost/v1/tickets \
  -H "Authorization: Bearer $AURALIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"subject": 123, "priority": "nope"}'

{
  "error": "validation_error",
  "message": "subject: Input should be a valid string",
  "detail": [
    { "loc": ["body", "subject"],  "msg": "Input should be a valid string",                          "type": "string_type" },
    { "loc": ["body", "priority"], "msg": "Input should be 'low', 'normal', 'high' or 'urgent'",      "type": "literal_error" }
  ]
}

message names only the first failure. If you are rendering errors against a form, read detail, not message.

Unknown fields are rejected, not ignored. Request models are strict, so a typo'd key is a 422 (extra_forbidden) rather than a silently dropped value. That is a deliberate trade: it costs you a round trip and saves you a field you thought you set.

Where the validator catches things a handler would have phrased better

An invalid UUID gives you two different errors depending on where it sits:

# In a query parameter — caught by a handler, gets a specific code
curl -sk "https://api.localhost/v1/tickets?team_id=not-a-uuid"
# 400 {"error":"invalid_uuid","message":"team_id must be a UUID", ...}

# In the path — caught by the parser first, gets the generic code
curl -sk "https://api.localhost/v1/tickets/not-a-uuid"
# 422 {"error":"validation_error","message":"ticket_id: Input should be a valid UUID...", ...}

Same for ?overdue=maybe, which is a 422 validation_error, not a filter error. Handle both shapes if you are validating user-supplied ids.

Three places the envelope does not hold

Stated plainly, because a client that assumes error is always present will throw on these:

The identifiers you will actually meet

The runtime defines over two hundred identifiers. Most are specific to one surface and are named on that operation's own page. These are the ones a general integration hits.

Credentials and identity

Permission

These are two independent axes — see Roles and permissions.

Input

An unknown filter value is an error, not an empty result. That is on purpose: ?status=opne returning zero rows would read as "no tickets", which is a much more expensive mistake than a 400.

State

illegal_transition is worth catching specifically, because its message enumerates what is legal:

{
  "error": "illegal_transition",
  "message": "illegal transition: open → open (legal: ['closed', 'on_hold', 'pending', 'solved', 'spam'])"
}

Better still, read legal_next_states off the ticket before you try — every ticket carries it.

Throttling

rate_limited (429) is the only one. It always means "come back later", never "rejected" — see Rate limits.

Retrying

Every response carries an x-request-id header. It is the only handle that ties your call to the runtime's logs, so capture it on failures.