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:

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 wallet_empty — strict-mode org wallet has zero balance
• 429 budget_exceeded — rolling per-key USD ceiling breached
• 503 no_available_channel — no operational channel serves this model
• 504 upstream_timeout — upstream didn't respond within the gateway window

The gateway already retries 503 no_available_channel and 504 upstream_timeout up to three times internally. By the time your client sees them, the fallback chain is exhausted.

When you should retry

Only retry 5xx platform errors and the 429 budget_exceeded after the indicated window passes. Everything else is deterministic from the request — retrying without fixing the cause just wastes credits.