Troubleshooting — OneRouter Docs

Common Error Codes

Code	Message	Cause	Fix
401	Invalid API key	Key is missing, malformed, or revoked	Check `Authorization: Bearer sk-...` header. Verify key is active in Dashboard → API Keys. Keys start with `sk-`.
402	Insufficient balance	Account balance is zero or negative	Add credits in Dashboard → Billing. Enable auto top-up for production keys.
404	Model not found	Model ID doesn't exist or is misspelled	Check the model name against available models. Model names are case-sensitive.
429	Rate limit exceeded	Too many requests or tokens in the current window	Check `x-ratelimit-remaining-*` headers. Implement exponential backoff. See Rate Limits.
500	Internal server error	OneRouter-side issue	Retry with backoff. If persistent >5 min, check status page.
502	Bad gateway	Upstream provider is down or timing out	Retry — auto-failover should route to your backup model. If persistent, configure a failover chain.
503	Service unavailable	Temporary overload	Wait and retry after the `Retry-After` header value. Check status page.

Connection Issues

"Connection refused" / "Name resolution failed"

Verify the base URL: https://api.onerouter.app/v1 (note: https://, not http://)
Check your firewall / proxy allows outbound HTTPS on port 443
DNS test: nslookup api.onerouter.app should return an IP
If you're in a region with restricted internet access, you may need to self-host

"SSL Certificate Error"

Ensure your system's CA certificates are up to date
Check that your system clock is accurate (SSL certificates are time-sensitive)
We use Let's Encrypt certificates — they're trusted by all major OSes

"Request Timeout"

Default timeout varies by SDK. Set explicitly: 60s minimum for chat, 120s for long generations
Use streaming (stream: true) — you'll receive tokens without waiting for the full response
If timeouts happen consistently with a specific model, the upstream provider may be slow — try a different model or add -fast suffix

Quick Diagnostic Checklist

Run through these before filing a support ticket:

Is your API key valid? — Test with this minimal curl:

curl -X POST "https://api.onerouter.app/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'

If this returns a 401, the key is the problem. If it returns a 200 with content, your key and base URL are correct.

Is the model name correct? — Check the model catalog. Common mistake: using "gpt4" instead of "gpt-4o".
Do you have credits? — Check Dashboard → Billing. Balance must be > $0.
Are you being rate limited? — Check response headers for x-ratelimit-remaining-requests. If it's 0, wait for the window to reset.
Is the service up? — Check the API Status Page for ongoing incidents.

SDK-Specific Issues

Python (openai SDK)

ModuleNotFoundError: openai → pip install openai
openai.APIError / APIConnectionError → Check network connectivity. Try curl directly to isolate SDK vs. network issues.
Proxies: Set http_client=httpx.Client(proxy="http://proxy:8080") if behind a corporate proxy

Node.js (openai SDK)

Cannot find module 'openai' → npm install openai
ERR_MODULE_NOT_FOUND → Use import with ESM or require('openai') with CJS
fetch is not defined (Node < 18) → Upgrade to Node 18+ or polyfill globalThis.fetch

Still Stuck?

Include the following when contacting support — it dramatically speeds up resolution:

Your account email
The request ID from the error response (id field)
Full error response body and HTTP status code
The model you're calling and a minimal code snippet that reproduces the issue
Your SDK version (pip show openai / npm list openai)

Email us at support@onerouter.app — we respond within 24 hours.