Errors

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.

409 Conflict

A handful of endpoints (for example, batch update of conversations) return 409 when the request makes sense but the underlying state machine rejects it (for example, trying to set a status that 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

Rate limit exceeded. See Pagination & rate limits for the rate-limit tiers (including the global 300 req/min limit) and the Retry-After header semantics.

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

500 Server Error

Unexpected exception. 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 auth endpoints return a machine-readable error code alongside the human-readable message: