Skip to main content

​
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
# 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 for valid model strings. 
# 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 to see current status. If multiple providers are down simultaneously, wait a few minutes and retry. If the problem persists, contact 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 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. 
# 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 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 or email 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)