DocsOperate
Troubleshooting
The first three things to check before you assume something's actually broken.
4 min read
Start here
GET /livezand/readyz— is the service up, and can it reach the database?GET /v1/providers/status— is the provider you're routing to actually healthy right now?POST /v1/routing/explainwith your request body — see exactly which candidates were considered, and why one won or lost.GET /v1/billing/entitlements— a 403 or 429 is often a plan boundary, not an outage.
Common issues
| Symptom | Likely cause | Check |
|---|---|---|
401 on /v1/chat/completions | API key missing or revoked | Dashboard → API Keys |
| Every request lands on the same provider | Routing policy pinned, or only one healthy provider exists | /v1/policies and /v1/providers/status |
| No failover on a provider error | The failure was non-retryable, or occurred after a stream had already committed | See Failover, precisely in AI & Routing |
| Cache never hits | Semantic threshold too strict, or caching disabled for the org | Dashboard → Cache |
| 429s under normal load | Plan quota reached | /v1/billing/usage and /v1/billing/entitlements |
"Cannot find module for page" on Windows
Environmental, not a bug in the code
An occasional Next.js production-build failure on Windows, caused by the App Router's catch-all route interacting with standalone output and webpack memory optimizations on Windows filesystems specifically. Doesn't reproduce on Linux, CI, or Vercel. If it hits you locally: delete .next and rebuild, or just develop against next dev and let CI own production builds.
Still stuck
Reach the team — see Contact on Business & Pricing — with the request ID from the response headers and the output of /v1/routing/explain for the failing request. That's usually enough to diagnose it in one round trip.
Related