OctaRouter forwards inference requests through octafuse-gateway. Errors fall into two categories: gateway checks before upstream, and upstream responses after forwarding (including failover).
Pass-through principle: once a request reaches an upstream provider, the HTTP status and JSON body follow that provider's official API — not a custom OctaRouter envelope. Gateway-generated errors use a simple
{ "error": "..." }string instead.
Gateway-generated errors
These happen before any upstream call (auth, model lookup, routing, budget). The body is always:
{ "error": "message" }
| Status | When |
|---|---|
| 401 | Missing API key, invalid key, or revoked key |
| 403 | Prepaid budget exhausted (Budget exceeded) |
| 404 | Model ID not found on this gateway deployment (Model not found) |
| 400 | Invalid JSON body, missing model, or no active route for the requested route group |
| 502 | No usable upstream route for this protocol, routing failure, or network error reaching a provider (Upstream request failed, etc.) |
Notes:
- Budget limits return 403, not 402.
- 404 means the gateway does not recognize the model ID — it is not an upstream "model does not exist" error.
- Fix these by checking your API key, account balance, model ID on the Models page, and request shape.
Upstream errors (pass-through)
After routing succeeds, the gateway forwards the request to one or more upstream providers (failover by priority within the same route group).
| Behavior | Detail |
|---|---|
| Non-2xx from upstream (including 429) | Try the next route in the group; if all fail, return the last upstream response unchanged (status + body) |
| Network / fetch failure | Try the next route; if all fail, gateway returns 502 with { "error": "Upstream request failed" } |
| Response body | Provider-native JSON — e.g. OpenAI { "error": { "message", "type", "code" } }, Anthropic { "type": "error", "error": { ... } }, Gemini Google-style JSON |
For request validation, streaming, tool errors, and other API semantics, follow the official docs for the protocol you use (linked from API protocols).
Rate limits (429)
The gateway does not apply its own API rate limits or return 429 itself.
429 comes from an upstream provider when you exceed their quota or throughput. If failover routes also return 429, you receive the last provider's 429 response as-is.
Client guidance for 429:
- Use exponential backoff with jitter
- Reduce concurrency or request rate
- Check the upstream error body for retry hints (
Retry-After, errorcode, etc.)
What OctaRouter does not define
OctaRouter docs do not maintain a separate catalog of upstream error codes. Treat provider responses as authoritative after a request has been forwarded.
Successful responses are also forwarded in the provider's native shape (with gateway-side request rewriting such as model mapping and provider credentials — see API protocols).