INTEGRATION GUIDE

Troubleshooting

All integrations

Fix common ZRouter connection problems: the gateway URL, API keys, model names, credit, BYOK, streaming, and coding agent compatibility errors, step by step.

On this page

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

Use https://zrouter.si for your account. Client-executed function tools with explicit text history can use account keys. Provider-hosted tools and opaque state are outside the supported account request shapes. 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.

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 Use client-executed function tools and inline text results; hosted tools, opaque state, and media are unsupported
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 supports client-executed tools, but does not remove hosted-tool, media, endpoint, or token restrictions. A client without custom-header support should use gateway-funded credits or a different compatible client.

Agent compatibility

Account keys now accept client-executed function definitions, tool calls, and text tool results. Send complete history on each turn. The Claude Code setup describes a supported text-file workflow. Server-hosted tools, opaque reasoning state, media, and stored response continuation remain blocked.

Disable unsupported features or choose a client workflow that sends supported account requests. Adding credit or changing keys does not remove the restrictions.

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.

Vendor configuration reviewed September 30, 2026. Model and client capabilities vary. Check the linked official sources when upgrading.