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 in the dashboard — Stripe, Alipay, WeChat Pay, and stablecoins are supported — or raise the key's maxSpend.
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.
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.
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.