Errors

The gateway returns OpenAI-compatible error envelopes with a DeepToken-specific category header so clients can branch retry behaviour without parsing strings.

The envelope

{
  "error": {
    "message": "human-readable description",
    "type": "category_name",
    "code": "specific_code"
  }
}

Every response also carries an X-Gateway-Error-Category header. The category is one of:

Category	Meaning	Retry?
`platform_error`	DeepToken-side fault	Yes, with backoff
`upstream_error`	Upstream provider failure	Retry only when the subtype and request semantics allow it
`quota_error`	Wallet, budget, or rate-limit signal	Top up, adjust the budget, or wait for the window
`user_error`	Bad request, authentication, or permission failure	Fix the request

Common codes

401 invalid_api_key — key revoked or never existed
403 model_not_allowed — your key's allowlist forbids the model
403 ip_not_allowed — request IP is not in the key's allowlist
402 org_wallet_empty — strict-mode org wallet has zero balance
403 budget_limit_exceeded — project or API-key budget ceiling breached
429 rate_limit_exceeded — request rate exceeded the configured window
503 no_available_channel — no operational channel serves this model

The gateway may route retryable upstream failures to another eligible channel. When an error reaches the client, inspect the HTTP status, error.code, category, and subtype before deciding to retry.

When you should retry

Retry 5xx platform_error responses with exponential backoff and jitter. Wait for the configured window after rate_limit_exceeded; adjust the budget or wait for its period after budget_limit_exceeded. Authentication, permission, model, and validation errors must be fixed before retrying.

The envelope

{
  "error": {
    "message": "human-readable description",
    "type": "category_name",
    "code": "specific_code"
  }
}

Every response also carries an X-Gateway-Error-Category header. The category is one of:

Category	Meaning	Retry?
`platform_error`	DeepToken-side fault	Yes, with backoff
`upstream_error`	Upstream provider failure	Retry only when the subtype and request semantics allow it
`quota_error`	Wallet, budget, or rate-limit signal	Top up, adjust the budget, or wait for the window
`user_error`	Bad request, authentication, or permission failure	Fix the request

Common codes

401 invalid_api_key — key revoked or never existed

403 model_not_allowed — your key's allowlist forbids the model

403 ip_not_allowed — request IP is not in the key's allowlist

402 org_wallet_empty — strict-mode org wallet has zero balance

403 budget_limit_exceeded — project or API-key budget ceiling breached

429 rate_limit_exceeded — request rate exceeded the configured window

503 no_available_channel — no operational channel serves this model

The gateway may route retryable upstream failures to another eligible channel. When an error reaches the client, inspect the HTTP status, error.code, category, and subtype before deciding to retry.