FAQ & Troubleshooting
The questions we hear most from developers wiring up the gateway — with the exact place to look when something fails.
Which base URL do I use — with or without /v1?
OpenAI-compatible clients (OpenAI SDK, Chat Completions, Responses, images, videos, Codex CLI) use https://api.router.one/v1 — with /v1. Anthropic-compatible clients (Anthropic SDK, Claude Code) use https://api.router.one — without /v1, because the client appends /v1/messages itself. A 404 right after setup is almost always this.
I get 401 Unauthorized. What should I check?
Three things, in order: the key was copied in full (starts with sk-, no trailing spaces); the request sends it as Authorization: Bearer <key>; and the key still exists and hasn't expired in Dashboard → API Keys. For Claude Code, also check ~/.claude/settings.json — its env block overrides shell environment variables, so an old key there wins over a new export.
I get 402 Payment Required.
The key is valid but the wallet balance (or the key's spend limit) is exhausted. Top up with a card or Alipay through one hosted checkout, or with USDT/USDC on six chains (Tron, BSC, Ethereum, Polygon, Base, Arbitrum) — or raise the key's maxSpend.
Dashboard →Pricing →Product & billing FAQ →Error codes reference →
I get 429 Too Many Requests.
No low fixed cap for normal paid usage. Abuse prevention, per-account protection limits, and upstream constraints may still apply; if a request returns 429, check Dashboard -> Logs or contact support to raise limits. Read Retry-After and back off; the code names the limit (RATE_LIMIT_EXCEEDED, TOKEN_QUOTA_EXCEEDED, SUBSCRIPTION_QUOTA_EXCEEDED).
A request came back 200 but the message content is empty.
That is a completed response, not an error, so don't auto-retry it. Models sometimes spend tokens without writing an answer — a system prompt that tells them to stay silent, a reasoning pass that ends without output, or a refusal carried in message.refusal. The reply is passed through as it came back, and settlement follows the usage the response reports, so a retry loop pays for the same silence again. Check finish_reason, refusal and usage on the reply first. A reply that reports no usage at all is the failure case: it is treated as an upstream error and another candidate for the same model is tried.
Claude Code still shows the official login screen (or answers from the wrong account).
That means the gateway env vars aren't visible to Claude Code. The one-click script writes ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN into the env block of ~/.claude/settings.json — verify they're there, then restart Claude Code. If you configured shell exports manually instead, open a new terminal so the exports load, and make sure no old value in settings.json overrides them.
Codex says the ROUTER_ONE_API_KEY environment variable is missing.
Codex reads your key from the ROUTER_ONE_API_KEY environment variable (declared as env_key in ~/.codex/config.toml). The install script appends the export to your shell profile — run source ~/.zshrc (or your shell's profile) in the current terminal, or open a new one. On Windows the variable is set at user level and new sessions pick it up automatically.
Do streaming, tool calling, and structured outputs work the same across models?
The request shape does: set stream: true on the same endpoint for SSE chunks in the official shape, declare tools once in the OpenAI-compatible tools array, and send response_format (json_object, or json_schema with a named schema) on the same request. Support still varies by model — the catalog marks tool calling per model, and schema enforcement is the model's, not the gateway's. The gateway checks the response_format envelope and returns 400 before any model call when json_schema, its name, or its schema is missing. Per-model differences show up in the request trace in Dashboard → Logs.
Streaming guide →Tool calling guide →Structured outputs guide →
Where do I find model IDs, and what does model: "auto" do?
The model catalog lists every model ID with pricing, context window, and capabilities — IDs are case-sensitive, so copy them exactly. With auto, the gateway routes inside a server-owned candidate set using latency, posted cost, and reliability signals; pin an exact ID when you need a specific model.
How do I see what each request cost?
Every request through the gateway is recorded with model, tokens, cost, latency, status, and the routing decision. Dashboard → Logs shows per-request records; Dashboard → Usage aggregates spend over time. If a request never appears in Logs, it never reached the gateway — the failure is local (base URL, key, or network).
How do I connect other tools (LangChain, Cherry Studio, Cline, …)?
Any tool that lets you set a custom OpenAI-compatible base URL works: set the base URL to https://api.router.one/v1, paste your sk- key, and pick a model ID from the catalog. For tools that speak the Anthropic protocol, use https://api.router.one instead.
Does it work from Mainland China?
Yes — the gateway is directly reachable from Mainland China without a VPN, and the configuration is identical everywhere.
Image or video requests seem slow — should I set a client timeout?
Generation endpoints are slower than chat by nature: image generation typically takes tens of seconds, and video generation is asynchronous — submit returns a task_id you poll via GET /v1/videos/generations/{task_id}. Avoid short client timeouts; for chat, prefer streaming so output arrives as it's generated.