# Connection checks & troubleshooting

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

## 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

```bash
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](/docs/integrations/claude-code) 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.