Errors

Error response envelopes, HTTP status behavior, validation failures, and machine-readable auth codes.

Every error response is JSON. The shape depends on which framework layer generated it, but every error has at least a message field.

The envelope

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Status code catalog

400 Bad Request

The body is malformed JSON, or the request includes a field that the endpoint does not recognize.

401 Unauthorized

The bearer token is missing, expired, or revoked. Refresh the token and retry.

{"message": "Unauthenticated."}

403 Forbidden

The token is valid but does not include the scope required for this endpoint, or the authenticated user does not have access to the requested resource.

404 Not Found

The resource does not exist, or it exists but belongs to a different organization. The API does not distinguish between the two.

405 Method Not Allowed

The HTTP verb is not supported by this path. Check the API reference.

A handful of endpoints, such as batch conversation updates, return 409 when the request makes sense but the underlying state machine rejects it—for example, when a status is not reachable from the current state.

412 Precondition Failed

Returned by POST /v1/inboxes/{inbox_id}/batch/update when no update field is provided.

{"message": "Nothing to update"}

422 Unprocessable Entity

The request body failed validation. The errors object is keyed by field name with an array of human-readable messages.

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email has already been taken."],
    "tags": ["The tags field is required."]
  }
}

429 Too Many Requests

The rate limit was exceeded. See Pagination and rate limits for the rate-limit tiers and Retry-After semantics.

{"message": "Too Many Attempts."}

500 Server Error

An unexpected exception occurred. The API does not return a stack trace in production. The incident is logged server-side with a UUID; include the request ID when contacting support.

503 Service Unavailable

Returned by POST /v1/auth/registration/register when the signup pipeline is temporarily unavailable.

{"message": "Registration Failed."}

Error codes on auth endpoints

Several authentication endpoints return a machine-readable error code alongside the human-readable message:

Code	Where	Meaning
`ERROR_EMAIL_INVALID`	`validate-email`, `register`	Address is malformed or in a blocked domain.
`ERROR_EMAIL_TAKEN`	`validate-email`, `register`	A user already exists with this address.
`ERROR_EMAIL_PENDING_APPROVAL`	`login`, `validate-email`, `register`	The account is awaiting approval.
`ERROR_EMAIL_FLAGGED`	`register`	The address is on a block list.
`ERROR_SLUG_TAKEN`	`validate-subdomain`	The subdomain is already in use.