error field describing what went wrong:
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.