Connection and usage
Base URLs, auth headers, and telling misconfiguration apart from failure.
Which base URL do I use?
It depends on the protocol your client speaks, not on which model you want:
| Your client speaks | Base URL |
|---|---|
| OpenAI | https://api.routemux.com/v1 |
| Anthropic | https://api.routemux.com |
| Google GenAI / Vertex | https://api.routemux.com/vertex-ai |
Why OpenAI keeps /v1 and Anthropic does not
OpenAI clients append only the operation path (/chat/completions), so /v1 belongs in
the base URL. Anthropic clients append /v1/messages themselves, so putting /v1 in the
base URL yields /v1/v1/messages. Getting these backwards is the most common setup error.
How do I authenticate?
Authorization: Bearer sk-... works everywhere. x-api-key (Anthropic style) and
x-goog-api-key (Google style) are also accepted, so SDKs work unmodified.
Sending several key headers with the same value is fine. Sending different values
returns 400 AMBIGUOUS_API_KEY — usually a stale key left in a field you stopped using.
Which models can I call?
GET /v1/models returns exactly the set your key can call. It is a metadata query and is
not billed. Treat it as the source of truth: a model that is not in that response will fail
no matter how the client is configured.
What does each error mean?
| Status | Meaning | What to do |
|---|---|---|
401 | Key missing, malformed, or revoked | Check the key starts with sk- and has no stray whitespace |
402 | Wallet balance is zero | Top up, then retry. This is not a request problem |
429 | Rate limited | Lower concurrency; retrying harder makes it worse |
503 | Upstream overloaded | Retry with backoff |
400 AMBIGUOUS_API_KEY | Two different keys sent | Clear the header you are not using |
Does streaming work?
Yes, unchanged. RouteMux forwards SSE without buffering the whole response, and settles billing on real usage once the upstream finishes.