Troubleshooting — TokSpan 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-`.
404	Endpoint not found	The request URL doesn't match any API endpoint	Check the request path against the API reference. Note: model-not-found errors are returned as `503` with code `model_not_found` — see Error Codes.
429	Rate limit exceeded / insufficient quota	Too many requests in the current window, or your account/API-key balance is exhausted	Implement exponential backoff with jitter for rate limiting. If the error message mentions quota or balance (e.g. `insufficient_user_quota`), top up in Dashboard → Billing instead of retrying. See Rate Limits.
500	Internal server error	TokSpan-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 a backup provider serving the same model. If persistent, contact support.
503	Service unavailable / model not found	Temporary overload, or the model isn't available to your key	Retry with backoff — don't rely on a `Retry-After` header. If the error carries code `model_not_found`, check the model name in the model catalog; names are case-sensitive. Check the status page.

Connection Issues

"Connection refused" / "Name resolution failed"

Verify the base URL: https://api.tokspan.com/v1 (note: https://, not http://)
Check your firewall / proxy allows outbound HTTPS on port 443
DNS test: nslookup api.tokspan.com should return an IP

"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 faster or lighter model instead

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.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_NAME","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 or out of quota? — If you get a 429 response, reduce concurrency and retry with exponential backoff (use the Retry-After header if present). If the error mentions quota/balance, check your credits in Dashboard → Billing.
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@tokspan.com — we respond within 24 hours.