Errors

What each failure means and which ones are worth retrying.

Table of Contents

Every error carries a code, a human readable message, and a requestId.

{
  "error": {
    "code": "scope_missing",
    "message": "The key is not scoped to read entities.",
    "requestId": "req_01H..."
  }
}

Status codes

Status	Meaning	Retry
`400`	The request is malformed.	No
`401`	The key is missing or invalid.	No
`403`	The key is valid but lacks the scope.	No
`404`	No such resource in this workspace.	No
`409`	The resource changed underneath you.	After reading it again
`429`	Rate limited.	Yes, after `Retry-After`
`5xx`	Our fault.	Yes, with backoff

401 means we do not know who you are. 403 means we do, and the key may not do that. Widening a key's scope fixes the second and never the first.

Send the requestId. It resolves in seconds what a description resolves in days.

更新于 2026年8月28日