Troubleshooting

Start with the right URL

Client or protocol	Base URL
Claude Code / Anthropic SDK	https://zrouter.si for supported text requests
Codex / OpenAI SDK / compatible chat tools	https://zrouter.si/v1 for hosted text requests
n8n HTTP Request	https://zrouter.si/v1/chat/completions

Hosted customers use https://zrouter.si. Coding agents that send tools require a separate standalone gateway and its operator-provided URL, not the hosted service. Include any operator-configured path prefix before /v1 on that deployment. Do not include /dashboard, /docs, or an inference endpoint in a client's base URL field. Do not append /v1 twice.

Verify authentication before inference

curl "$ZROUTER_URL/v1/models" \
  -H "Authorization: Bearer $ZROUTER_API_KEY"

For prepaid accounts, use an active account API key created in your dashboard. A browser session token, provider key, or operator master key is not an account inference credential. All account keys share the owning account's balance and access scope.

For a standalone gateway, use a dedicated operator-managed gateway key. A managed key from that deployment cannot replace a prepaid account key on a different deployment.

Read the error

Status / symptom	Check
401	Correct deployment, active key, bearer header, and any client environment variables
402	Sufficient available credit for the reservation; lower maximum output or buy credit
403 unsupported endpoint	Prepaid endpoint allowlist, key permissions, or account access
400 tools or content rejected	Prepaid supports text inputs, not tool exchanges or media
Model missing / model not found	Exact enabled identifier, provider instance, and provider entitlement
BYOK key missing	Saved key for the same provider instance, provider-qualified model, and BYOK header
429	Workspace, key, or upstream provider rate limits
503	Account/billing service or upstream availability; inspect the sanitized error
Stream stops	Client/network disconnect, proxy buffering/timeouts, and final usage availability

Providers may use additional statuses and error messages. Record the status and request time, but never include API keys or authorization headers when sharing diagnostics.

Credit and token limits

Set a reasonable max_tokens for Chat Completions/Messages, or max_output_tokens for Responses. The live workspace limit appears in the API guide. Provider limits may be lower. The initial reservation can exceed the final actual charge, so a positive balance alone does not guarantee a request can start.

Large agent histories can exceed the input allowance. Prepaid input validation also uses a conservative request-size bound. Shorten the text history and reduce output instead of repeatedly sending the same rejected payload.

BYOK checklist

1. Save a supported provider credential under your own ZRouter account.
2. Use PROVIDER_INSTANCE/MODEL_ID for that connection.
3. Send your ZRouter account key for gateway authentication.
4. Send X-ZRouter-BYOK: true on the inference request.
5. Check provider quota and any ZRouter routing fee, including a negative account balance.

Saving a provider key does not automatically enable BYOK. BYOK does not remove prepaid tool, media, endpoint, or token restrictions. A client without custom-header support should use gateway-funded credits or a different compatible client.

Agent tools are a deployment limitation

Claude Code, Codex, Cline, OpenCode, and Cursor Agent send tool requests. The current prepaid middleware rejects nonempty tools and structured tool content, plus stored response continuation. This cannot be corrected by adding credit, changing a model label, or using a master key.

Use a separate standalone gateway for those workflows. Prepaid agent support requires additional metering and compatibility implementation before it can be offered for prepaid accounts.

Networking and usage

CLI clients run locally; container clients need an address reachable from their container. Cursor's backend needs public HTTPS. A successful /models request checks connectivity and credentials but not generation, streaming, or tool support.

Check token totals in Usage, available requests in Logs, and actual balance changes in Billing. A shared client key charges one account even when external user headers differ. Completed retries can consume tokens again; disconnected streams can retain reservations for reconciliation.