Error Codes

Use this page to understand the stable machine-readable error codes you should branch on in clients and automations.

Who This Is For

SDK maintainers
developers implementing retries and user messaging
AI agents making structured decisions from error responses

When To Use This

Read this page whenever you need to switch on backend failures programmatically.

How It Works

Error responses use:

json

{
  "error": {
    "code": "TOKEN_SCOPE_DENIED",
    "message": "scope denied",
    "detail": "requires report:export"
  },
  "meta": {
    "request_id": "req_123"
  }
}

Common stable codes by category:

Query and validation

INVALID_QUERY
VALIDATION_ERROR
BAD_REQUEST

Auth and authorization

TOKEN_SCOPE_DENIED
runtime auth denials and license-status failures such as LICENSE_INACTIVE and LICENSE_EXPIRED

Existence and conflicts

NOT_FOUND
IDEMPOTENCY_CONFLICT
feature or activation conflicts such as FEATURE_QUOTA_EXCEEDED and ACTIVATION_LIMIT_EXCEEDED

Runtime device or policy enforcement

DEVICE_BLACKLISTED
OFFLINE_NOT_ALLOWED

Treat error.code as the stable branch key. Treat message and detail as explanatory text.

Example

if (error.code === "TOKEN_SCOPE_DENIED") {
  // create or load a token with the route's x-required-scopes
}

Common Mistakes

branching on message instead of code
treating all 4xx errors as retryable
losing request_id when logging or escalating failures

Error Codes ​

Who This Is For ​

When To Use This ​

How It Works ​

Query and validation ​

Auth and authorization ​

Existence and conflicts ​

Runtime device or policy enforcement ​

Example ​

Common Mistakes ​

Related Pages ​