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
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

One that surprises 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.

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`
`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

One that surprises people

404 for another workspace’s data

Validation changes nothing

Retrying

​Branch on code, never on message

​The codes

​One that surprises people

​404 for another workspace’s data

​Validation changes nothing

​Retrying

Branch on `code`, never on `message`

The codes

One that surprises people

404 for another workspace’s data

Validation changes nothing

Retrying