Errors

Every failed request returns a standard HTTP status code and a JSON body with a single error field describing what went wrong:

{ "error": "message is handled, not awaiting_review" }

Branch on the HTTP status. Treat error as a human-readable message for logs and developers, not a stable machine code.

Status codes

Status	Meaning	Typical cause
`400 Bad Request`	Malformed, or not valid for the resource’s current state	Missing/invalid field, an unknown enum value, or a wrong-state action (e.g. replying to a message that isn’t `awaiting_review`)
`401 Unauthorized`	No valid credential	Missing, malformed, expired, or revoked token
`402 Payment Required`	A plan or credit limit blocks the action	Out of credits; the plan’s email-inbox limit reached
`403 Forbidden`	Authenticated but not allowed	The token lacks the required scope; not an admin; not a participant of the resource
`404 Not Found`	No such resource for this caller	Unknown id — or a resource in another workspace
`409 Conflict`	Collides with existing state	e.g. an email address already in use
`429 Too Many Requests`	Rate limit exceeded	See Rate limits
`503 Service Unavailable`	A dependency isn’t configured or available	e.g. billing not configured
`500 Internal Server Error`	Unexpected server error	Retry; if it persists, contact support

For resources outside your workspace HQ returns 404, not 403, so the API never reveals whether an id you can’t access exists.