Errors

Any failure, on any surface, comes back in one shape:

{
  "error": {
    "code": "validation_failed",
    "message": "Give an email address or an external_id",
    "field": "requester.email"
  }
}

The REST API, the MCP server, and the widget all use it. A client that had to branch on which surface it was talking to would sooner or later get the branch wrong.

Branch on `code`, never on `message`

code is the contract. It comes from a fixed set, and its meaning never changes. message is written for a human reading a log. We may reword it at any time. Anything that matches on the text of a message is a bug waiting for a copy edit. field appears on validation failures. It is a dotted path into the body you sent.

The codes

Status	`code`	When
400	`validation_failed`	The body failed schema validation. `field` names the cause, and nothing was changed
401	`invalid_credential`	Missing, malformed, expired, or revoked token
402	`quota_exhausted`	Out of conversations for this period. See Quotas
403	`forbidden`	Authenticated, but this role cannot do this
404	`not_found`	Unknown id, or another workspace’s resource
409	`conflict`	A unique constraint you can see, such as a reused reference
422	`invalid_transition`	A status change the state machine does not allow
429	`rate_limited`	Over the limit. `Retry-After` says when to come back
500	`internal_error`	Ours. `X-Request-Id` identifies the occurrence
503	`service_unavailable`	A dependency we do not control is down, such as the model provider

Two that surprise people

404 for another workspace’s data

Asking for a ticket that belongs to someone else returns not_found, exactly as if it did not exist. It never returns 403. That is by design. A 403 would tell you the id is real, and being able to probe for which ids exist in other workspaces is itself the leak.

402 rather than 403 when you run out

quota_exhausted is a billing state, not a permissions one. Your credentials are fine, and you are allowed to do this; the account is not paid up. The distinction matters for clients. Something treating 403 as “log in again” would send an integration round an auth loop over an unpaid invoice.

Validation changes nothing

A 400 means the request was rejected before anything acted on it. There is no partial write to undo. Fix the field named in field, then send it again.

Retrying

Retrying a POST without an Idempotency-Key is how you get duplicate tickets. See Idempotency.

Code	Retry?
`rate_limited`	Yes, after `Retry-After`
`service_unavailable`	Yes, with backoff
`internal_error`	Yes, with backoff. Keep the `X-Request-Id`
`quota_exhausted`	No. Nothing changes until the period resets or the plan does
`validation_failed`	No. The same body will fail the same way
`invalid_credential`	No
`not_found`	No
`invalid_transition`	No. Read the current status first

Getting started

Core concepts

Branch on `code`, never on `message`

The codes

Two that surprise people

404 for another workspace’s data

402 rather than 403 when you run out

Validation changes nothing

Retrying

​Branch on code, never on message

​The codes

​Two that surprise people

​404 for another workspace’s data

​402 rather than 403 when you run out

​Validation changes nothing

​Retrying

Branch on `code`, never on `message`

The codes

Two that surprise people

404 for another workspace’s data

402 rather than 403 when you run out

Validation changes nothing

Retrying