Errors

Every non-2xx response uses a consistent envelope:

{
  "error": {
    "code": "forbidden_scope",
    "message": "This token is missing the 'clients:write' scope required for this endpoint.",
    "request_id": "5f6c1b0e-8a2e-4d1a-9d3c-1a2b3c4d5e6f",
    "details": { }
  }
}

code — a stable, machine-readable identifier you can branch on.
message — a human-readable explanation.
request_id — also returned as the X-Request-Id response header; use it to find the request in your logs (see below).
details — present on validation errors; a field-level breakdown.

Error codes

HTTP	`code`	Meaning
400	`invalid_request`	Malformed body or query params. See `details`.
401	`unauthorized`	Missing bearer token.
401	`invalid_token`	Token is malformed or unknown.
401	`token_revoked`	The key was revoked.
401	`token_expired`	The key passed its expiry date.
402	`plan_limit_reached`	The organization is over a plan limit.
403	`forbidden_scope`	The token lacks the required scope.
403	`forbidden`	Not allowed for this resource.
404	`not_found`	No such resource in this organization.
409	`conflict`	Conflicting state (e.g. a timer is already running).
429	`rate_limited`	Too many requests. See Rate limits.
500	`server_error`	Unexpected server error. Retry; contact support with the `request_id`.

Every API and MCP request is recorded. In Settings → Developers → Request logs you can see each call's method, path, status, latency and — when it failed — the request_id and error code, so you can debug integrations without guessing. The usage panel above it summarizes request volume, success rate and status breakdown over the last 7 or 30 days.

Error codes

Request logs

On this page