Capacity, Spillover and Errors
How the provider stays up under load, where excess traffic goes, and what each error code means.
The provider is built to absorb far more concurrent callers than its own budget can serve directly. Instead of dropping the excess, it hands it to a spill pool; instead of queueing forever, it sheds with a clear, retryable error.
How load is handled
| Tier | Behaviour |
|---|---|
| Primary | Served on ZYRAXON's own lane budget. Responses carry X-ZYRAXON-Capacity: primary. |
| Spill | When primary lanes are full, the turn is handed to the OpenCode Zen free pool. Still a normal, successful answer, marked spill. |
| Queue | A bounded wait for a lane before giving up, so a short burst is smoothed rather than rejected. |
| Shed | If even the spill tier is saturated, the request returns 503 with Retry-After rather than blocking other callers. |
✓
Overload degrades, it does not crash
A
spill response is a success. Treat X-ZYRAXON-Capacity: spill as a signal to slow down or add retry jitter, not as an error to surface.Error codes
| Status | type | Meaning and what to do |
|---|---|---|
| 400 | invalid_request_error | Unknown model, missing messages, or malformed JSON. Check the model id against /v1/models. |
| 401 | authentication_error | The deployment requires a provider key and yours is missing or wrong. Send Authorization: Bearer <key>. |
| 413 | payload_too_large | Body over the limit. Compress and slice media, then retry. |
| 429 | rate_limit | Slow down and retry with backoff. |
| 502 | provider_unavailable | Every model in the rotation was unavailable. Retrying usually works. |
| 503 | overloaded | At capacity; shed rather than queued. Honour Retry-After. |
| 503 | upstream_gate | The upstream free tier refused this network. Set OPENCODE_ZEN_API_KEY or call from a served network. |
Recommended retry policy
- ▸Retry
429,502,503with exponential backoff plus jitter. - ▸Honour the
Retry-Afterheader on503. - ▸Do not retry
400,401, or413— fix the request instead. - ▸Log the
typefield, not just the status:overloadedandupstream_gateare both 503 but need different actions.
★
Check status before a big run
GET /api/public/zyraxon/v1/provider reports live model health, the current concurrency ceiling, and the overload policy, so a client can decide before it fires a batch.