Handle errors and prepare for production

Interpret XiuRouter errors, choose safe retries, and check API keys, timeouts, logging, and rollback before release.

XiuRouter errors usually include error.message, error.type, and error.code. Record the x-oneapi-request-id response header, then use the HTTP status and usage logs to decide what to do. The XiuRouter FAQ also groups common causes.

Read an error response

A request without a valid key returns a response similar to:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

Do not extract or log API keys, upstream credentials, complete prompts, or sensitive inputs from error messages.

Common status codes

Status	Common cause	Next step
`400`	Invalid JSON, parameter, or protocol	Reduce the request and correct the reported field; do not retry automatically
`401`	Missing, invalid, or revoked key	Check the process environment and key status; rotate the key when needed
`403`	Account, IP, group, model, or quota restriction	Check the key scope, balance, and service group
`404`	Unknown endpoint	Check the Base URL and path; `/v1/messages/count_tokens` currently has no dedicated route, but Claude Code can fall back to Messages
`429`	Request rate exceeds the current limit	Reduce concurrency and use bounded retries after waiting
`5xx`	Temporary gateway or upstream failure	Record the request ID and check usage logs before retrying

When no channel is available for a model, the gateway may return 503 with model_not_found. Check the key’s service group, model scope, and current catalog before assuming the model ID is misspelled.

Decide whether to retry

For 400, 401, 403, or 404, fix the request or configuration first.
For 429, some 5xx responses, or a disconnected network, use bounded backoff and a total time limit.
A timeout or interrupted connection may have an unknown result. Check usage logs by request ID, time, and model before submitting again.
Tool calls, external writes, and other operations that must not repeat need application-level idempotency. XiuRouter does not guarantee that your business operation executes only once.

Do not assume another provider’s fixed retry counts or error semantics apply. XiuRouter can forward or transform upstream errors; consider the status, error object, and usage logs together.

Prepare for production

Create a dedicated API key for each application.
Select an explicit service group. With automatic grouping, check the attempt order and whether retries across groups can change cost.
Restrict models, remaining quota, and expiration.
Check any IP restrictions already on the key; the console currently has no editor for them.
Use https://router-api.xiu.ai/v1 for OpenAI Chat/Responses and https://router-api.xiu.ai for Anthropic Messages/Gemini. Do not configure new clients with the console domain.
Store keys in server-side secrets or the runtime environment, outside browser bundles, repositories, and logs.
Set connection, first-token, and total-request timeouts; do not rely only on defaults for long streams.
Log request IDs, models, protocols, duration, and results without complete credentials or sensitive inputs.
Alert on 429, 5xx, and unknown results, and regularly reconcile usage logs.
Keep the old provider configuration and rollback steps. Begin with a small volume of read-only requests.

Verify before release

Test text, streaming, tools, and structured output separately as required by the application.
Check the key’s models, group, quota, expiration, and IP scope.
Confirm that failed requests have a request ID you can locate in the console.
Handle timeouts, 429, upstream 5xx, and insufficient balance explicitly.
Verify that rollback sends new requests to the original provider and that the old XiuRouter key can be revoked.

Sources and review date

Authentication, routing, limits, error shape, FAQ, and usage-log behavior were reviewed on 2026-08-30. This translation preserves that review date. XiuRouter has not published a fixed SLA and does not guarantee uninterrupted third-party upstream service.