> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and how to fix them.

## HTTP Errors

### `401 Unauthorized`

**Cause:** API key missing, malformed, or revoked.

**Fix:**

* Make sure you're passing the key in the `Authorization: Bearer sk-routor-...` header
* Verify the key starts with `sk-routor-` (not an OpenAI key)
* Check that the key hasn't been revoked in **Dashboard → API Keys**
* If you're using a routing profile key, check **Playground → Manage Profiles** to confirm the profile still exists

```bash theme={null}
# Correct
curl https://api.routor.io/v1/chat/completions \
  -H "Authorization: Bearer sk-routor-YOUR_KEY"

# Wrong - missing Bearer prefix
curl https://api.routor.io/v1/chat/completions \
  -H "Authorization: sk-routor-YOUR_KEY"
```

***

### `402 Payment Required`

**Cause:** Your credit balance is zero.

**Fix:** Top up in **Dashboard → Billing → Add Credits**.

There are no partial charges. Requests fail cleanly when credits run out - your app catches a 402, you top up, requests resume.

***

### `404 Not Found` on the model

**Cause:** You passed a specific model name that Routor doesn't proxy directly.

**Fix:** Use `model: "auto"` to let Routor pick, or check [Supported Models](providers/supported) for valid model strings.

```python theme={null}
# Wrong - Routor is not a pass-through to OpenAI model names
client.chat.completions.create(model="gpt-4o", ...)

# Correct - let Routor route
client.chat.completions.create(model="auto", ...)
```

***

### `422 Unprocessable Entity`

**Cause:** Malformed request body - usually a missing `messages` field or invalid `role`.

**Fix:** Ensure every message has a `role` (`user`, `assistant`, or `system`) and a `content` string.

***

### `429 Rate Limited`

**Cause:** You've hit a per-minute request limit (rare on the default plan).

**Fix:** Add exponential backoff in your client. If you consistently hit this, contact support.

***

### `503 Service Unavailable`

**Cause:** All providers in the selected tier are currently failing.

**Fix:** This is extremely rare because of the fallback chain. Check [Provider Health](providers/health) to see current status. If multiple providers are down simultaneously, wait a few minutes and retry. If the problem persists, contact [support@routor.io](mailto:support@routor.io).

***

## Routing Issues

### "My responses feel too generic / low quality"

**Cause:** The router is routing to a lighter tier than you expect.

**Fix:** Create a routing profile with a higher tier floor. Go to **Playground → Configure**, set the tier floor to STANDARD or COMPLEX, and save. Use the profile's API key for requests that need higher quality.

You can also test a specific prompt in **Playground → Test** to see exactly which tier and model get selected.

***

### "My response is slow - slower than before"

**Cause:** The request was routed to a model with higher latency than your previous provider.

**Fix:**

1. Check the `X-Routor-Model` header in the response to see which model was selected
2. If a COMPLEX tier model was chosen for a simple request, the scorer may be miscalibrating on your prompt style
3. Set a tier ceiling in your profile to cap at STANDARD and accept the quality trade-off
4. Contact support with a sample prompt - we can investigate calibration issues

***

### "Tool calling isn't working"

**Cause:** The routed model doesn't support tool calling, or you didn't set the capability requirement.

**Fix:**

* Create a routing profile with **Tool calling** capability enabled
* Use the profile's API key for requests that include `tools`
* Check [Supported Models](providers/supported) to confirm which models support tools

***

### "Vision isn't working - images are ignored"

**Cause:** The routed model doesn't support vision inputs.

**Fix:**

* Create a routing profile with **Vision** capability enabled
* Pass image content in the `image_url` format (OpenAI-compatible)
* Without the capability set, Routor may route to a text-only model

***

## SDK / Integration Issues

### `Error: baseURL must not end with a slash`

Some SDK versions are strict about the base URL format.

```python theme={null}
# Correct - no trailing slash
client = OpenAI(base_url="https://api.routor.io/v1")

# Wrong - trailing slash causes issues in some SDK versions
client = OpenAI(base_url="https://api.routor.io/v1/")
```

***

### Headers not appearing in response

`X-Routor-*` headers are only returned when Routor handles the routing. If you're pointing at `api.openai.com` or a different endpoint, you won't see them.

Verify your `base_url` (Python) or `baseURL` (Node.js) is set to `https://api.routor.io/v1`.

***

### Streaming stops mid-response

This can happen if the provider terminates the stream early (rare). The fallback system handles full request failures but not mid-stream failures. If you encounter this regularly, contact support with the model name from the `X-Routor-Model` header.

***

## Dashboard Issues

### Credits show \$0 but I just topped up

Payments via Razorpay are typically instant. If your balance doesn't update within 2 minutes:

1. Hard-refresh the dashboard (Cmd+Shift+R / Ctrl+Shift+R)
2. Check your email for a payment confirmation
3. Contact [support@routor.io](mailto:support@routor.io) with your payment ID

***

### API key shows "Last used: Never" even after making requests

The "last used" timestamp updates every few minutes, not in real time. If it still shows "Never" after 10 minutes, verify you're using the correct key prefix shown in the dashboard.

***

## Still stuck?

Open a [GitHub issue](https://github.com/routor-ai/routor/issues) or email [support@routor.io](mailto:support@routor.io) with:

* The error message and HTTP status code
* The `X-Routor-*` headers from the response (if available)
* A minimal reproduction (prompt + code snippet)