9Router proxy: endpoints, keys, and errors

The 9Router proxy is the gateway between your client and a model provider. In the default local setup, OpenAI-compatible clients use http://localhost:20128/v1. The dashboard address, API base URL, model ID, and credentials serve different purposes; mixing them is a common reason a seemingly correct setup fails.

Separate the two connections

Your client first authenticates to 9Router. Then 9Router authenticates to the selected provider. The client should use a router-issued key where local API authentication is enabled. The provider key or supported account connection stays in the router’s provider configuration.

Setting	Purpose	Common mistake
Dashboard URL	Open the administration UI	Using a dashboard path as an API base
API base	Let the client construct endpoint paths	Adding /chat/completions when the client already adds it
Router API key	Authorize local client requests	Pasting the wrong provider credential
Provider credential	Authorize upstream inference	Assuming a local key funds the upstream request
Model ID	Select a known route	Copying an unavailable model from a screenshot

An OpenAI-compatible chat endpoint is also not automatically a Responses or Anthropic Messages endpoint. Use the integration guide for Codex, Claude Code, or OpenCode so the client requests the correct API shape.

Check the server and model catalog

curl -i http://localhost:20128/api/health
curl -i http://localhost:20128/v1/models \
  -H "Authorization: Bearer $NINEROUTER_API_KEY"

Use your router key in the environment variable. A health response confirms an HTTP service is reachable. A model-list response establishes that the local API can list routes. Neither proves that a provider can complete inference.

Choose an exact ID from the catalog and send a minimal request through your client. Begin without a combo, custom reasoning options, tools, or a large conversation. Add streaming and tool use one at a time so a failure has a useful comparison.

What if the client is on another machine?

localhost always refers to the machine or container making the request. A phone, another workstation, and a Docker container cannot reach your laptop’s 9Router instance through their own localhost address. Use a reachable network address and verify the listening interface and firewall.

For remote access, protect both the API and administration interface. Use authenticated access and HTTPS across untrusted networks. Restrict who can reach the router rather than exposing a public keyless endpoint. A publicly accessible router can incur provider usage even when its own software is free.

Diagnose errors by the failing connection

• Connection refused: the local process, address, port, or listening interface is wrong.
• 401 from 9Router: check the key presented by the client and local authentication settings.
• 401 inside an upstream error: inspect the provider connection and its current authorization.
• 429: identify whose quota or rate limit is being enforced before retrying.
• 400: reduce the request and check model name, API shape, and optional parameters.
• A stream stops halfway: compare a short nonstreaming request, then inspect timeouts and intermediate proxies.

Issue #5120 reports a 503 wrapper containing an upstream Cline 401. It illustrates why the outer status alone can be misleading; it does not establish a universal fix for all 503 responses.

Why does a SOCKS5 proxy time out?

A SOCKS5 egress proxy is an additional network hop used to reach a provider. It is distinct from the 9Router API endpoint your coding client calls. Issue #5111 reports a SOCKS5 connection timeout; the report does not demonstrate a confirmed repair.

Check the proxy host and port from the router’s environment, its authentication requirements, and whether the installed version supports the configured proxy scheme. Remove credentials before sharing an error. If your direct provider connection is permitted and works, compare it with the proxy route to isolate that hop. Do not change several layers at once or treat a new proxy as a solution to an account quota limit.