Common Errors

Error response format

Model endpoints return errors as JSON:

{
  "error": {
    "message": "Insufficient user quota, remaining: ＄0.000000 (request id: 202610230158421013999388268d9d615)",
    "type": "error",
    "code": "insufficient_user_quota"
  }
}

• message is human-readable and ends with (request id: <id>). The same ID is returned in the X-Oneapi-Request-Id response header; include it when contacting support.
• code is the machine-readable error code. Some errors leave it as an empty string; use the HTTP status code in that case.
• message is localized (by the user’s language setting or Accept-Language) and may change, so base program logic on the HTTP status code and code.

Claude Messages (/v1/messages) returns {"type": "error", "error": {"type": "...", "message": "..."}} instead. Async task endpoints (/v1/video/generations, /v1/videos, /suno/*) return {"code", "message", "data"} for errors raised after routing, and that message does not carry the request ID.

401 Unauthorized

The API Key is missing, invalid, expired, disabled, or out of quota:

• The Authorization header is missing, or is not written as Bearer sk-....
• The key was deleted, disabled, or has expired.
• The key’s remaining quota is used up.
• A Management Key (rat_...) was sent to a model endpoint; model calls require an sk- API Key.

Create a new key on the API Keys page if needed. Key quota and expiry are described in Balance and Quotas.

403 Forbidden

403 has two different causes; check code in the response.

Insufficient balance or key quota

• insufficient_user_quota: the account balance cannot cover the estimated cost of this request, or the subscription has no remaining quota.
• pre_consume_token_quota_failed: the key’s remaining quota cannot cover the estimated cost.

Top up the account, raise the key quota, or lower max_tokens so the estimate fits. See Balance and Quotas.

No permission

These usually come back with an empty code; the message tells you which check failed:

• The key’s model restrictions do not include this model (This token has no access to model ...).
• The key’s group is not available to your account.
• The source IP is not in the key’s IP allowlist (code access_denied).
• The account is disabled.

429 Too Many Requests

The request rate limit was exceeded. Limits are counted per account: all keys under the same account share the quota, so adding keys does not raise the limit. Rejected requests are not billed.

• Retry with exponential backoff and random jitter.
• Reduce concurrency or spread requests over time.
• A 429 response may have an empty body; rely on the status code rather than on the message.

See Billing and Rate Limits for how model request limits work and how upstream 429s are retried.

503 Model not available

• code model_not_found with a message such as “No valid upstream service”: no channel currently serves this model for your group. Check the model ID spelling and whether the model is available to your account; retrying the same request immediately rarely helps.

502 / 503 Upstream error

• A 502 or other 5xx from the model provider is passed through when all retries fail.
• code get_channel_failed with “Upstream service is temporarily unavailable”: the upstream account behind the channel is unusable (for example, its balance or credentials failed). RouteAPI retries on another channel when possible, returns this generic message, raises an internal alert, and may disable the faulty channel; retry later.
• code client_failfast (503): the same API Key kept failing for this model at a high rate, so a short protection window was opened for that Key/model combination. The response carries Retry-After and X-Client-Failfast: 1; wait before retrying, and fix the failing request instead of retrying it unchanged.

Retry later when the error is temporary. If it persists, contact support with the request ID.