ToRouter DocsTroubleshooting
Common HTTP errors
Quick reference for 400 / 401 / 403 / 404 / 429 / 5xx responses from ToRouter and how to fix them.
ToRouter follows standard HTTP semantics. The status code tells you whether the problem is in your request, your key, your quota, or the upstream provider.
| Status | Meaning at ToRouter | Likely fix |
|---|---|---|
| 400 | Malformed body, invalid model name, unsupported parameter for the chosen model | Validate JSON; check the model slug in /models; drop unsupported fields |
| 401 | Missing, malformed, or unknown API key (API_KEY_REQUIRED, INVALID_API_KEY, API_KEY_DISABLED, USER_INACTIVE) | Re-check the Authorization: Bearer sk-*** header; confirm the key is enabled |
| 402 | Account balance insufficient (pay-as-you-go) | Top up in Billing → Top up |
| 403 | Access denied (ACCESS_DENIED for IP allowlist), API_KEY_EXPIRED, SUBSCRIPTION_NOT_FOUND, INSUFFICIENT_BALANCE, model not in the key's whitelist | Adjust the key's IP allowlist / model whitelist; renew; subscribe to the group |
| 404 | Model not present in your subscribed group's catalog, or unknown endpoint path | Open /models to see what your group exposes; verify the path matches the protocol (OpenAI vs Anthropic vs Gemini) |
| 429 | Rate limit hit (rate limit exceeded) or API_KEY_QUOTA_EXHAUSTED or daily/weekly/monthly subscription window limit | See Rate-limited |
| 500 | ToRouter internal error — retry with backoff | Retry; if it persists, report with the x-request-id response header |
| 502 | Every upstream candidate failed after failover attempts | See Upstream errors & failover |
| 503 | Service temporarily unavailable — no eligible channel right now | Retry; check /dashboard for channel health |
| 504 | Upstream timeout | Retry; consider a smaller model or shorter prompt |
Response shape
ToRouter returns errors as JSON with at least an error field. The exact shape mirrors the protocol you called (OpenAI / Anthropic / Gemini), with ToRouter-specific codes inside.
{
"error": {
"message": "API key 已过期",
"type": "API_KEY_EXPIRED",
"code": "API_KEY_EXPIRED"
}
}Always log the x-request-id response header. It lets support trace the exact gateway path your request took.