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 5xx / timeout | Already retried; do not retry |
quota_error | Your wallet / per-key budget is empty | No — top up |
user_error | Bad request / unknown model / disallowed model | No — fix request |
Common codes
401 invalid_api_key— key revoked or never existed403 model_not_allowed— your key's allowlist forbids the model403 ip_not_allowed— request IP is not in the key's allowlist402 org_wallet_empty— strict-mode org wallet has zero balance403 budget_limit_exceeded— rolling per-key USD ceiling breached503 no_available_channel— no operational channel serves this model
When you should retry
Only retry 5xx platform_error errors and the 403 budget_limit_exceeded after the indicated window passes. Everything else is deterministic from the request — retrying without fixing the cause just wastes credits.