Errors

When a request fails, SpiderGate returns a standard HTTP status code and a structured JSON body so your code can branch on the exact reason. This page lists every status code the gateway returns and what to do about each.

The error shape

Errors come back in an OpenAI-style envelope with a machine-readable type and code:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 61/60 requests per minute"
  }
}

Branch on code, not on the human-readable message (which may change).

Status codes

::table
Status | When | Typical code
`400` | Invalid request — bad JSON, a missing required field, or an out-of-range value | (validation)
`401` | Authentication failed — missing or invalid token | `missing_api_key`, `invalid_token_format`, `invalid_api_key`
`402` | The token's budget is spent | `budget_exceeded`
`403` | The token isn't allowed to use the requested model | `model_not_allowed`
`404` | Unknown resource — e.g. a model id that doesn't exist | `model_not_found`
`429` | Rate limit hit — per-minute or per-day | `rate_limit_exceeded`, `daily_rate_limit_exceeded`
`503` | The gateway can't serve right now — engine starting up, or no key for a required provider | `service_unavailable`, `no_openai_key`

What each means

400 — bad request

The request didn't validate: malformed JSON, an empty messages array, or a parameter out of range (e.g. temperature above 2.0). Fix the payload and retry. The multi-modal endpoints also return 400 for an unsupported voice (invalid_voice) or response_format (invalid_response_format).

401 — not authenticated

The token is missing or invalid. The response includes a WWW-Authenticate: Bearer header. Check the Authorization header format — see Authentication.

402 — budget exceeded

The agent token has reached its monthly spend cap and is configured to block. The message reports current spend vs. the cap. Raise the budget on the token, or wait for the monthly reset — see Rate Limits & Budgets.

403 — model not allowed

The token has an allowed-models list (or a free-only restriction) that doesn't include the model you asked for. Request an allowed model, or widen the token's list in Agent Keys.

429 — rate limited

The token exceeded its per-minute (rate_limit_exceeded) or per-day (daily_rate_limit_exceeded) request limit. The response includes a Retry-After header and X-RateLimit-* headers telling you the limit, what's remaining, and when it resets. Back off and retry after the indicated delay — see Rate Limits & Budgets.

503 — unavailable

Either the engine is still starting (service_unavailable) — retry shortly — or you've called a multi-modal endpoint with no OpenAI key in the vault (no_openai_key). For the latter, add an sk-… key via the contributor invite on The Key Vault.

Routing failures vs. errors

A single upstream model being busy or erroring is not an error you see — SpiderGate falls through the alias's chain and serves an alternative, signalling the substitution with the X-SpiderGate-Fallback-From header. You only get a 5xx when every candidate in the chain (and its cross-alias fallback) is exhausted. To see what was attempted, add ?include_route_trace=true — see Chat Completions.

Next steps

1. Stay under limits — Rate Limits & Budgets.

2. Check your token format — Authentication.

3. Diagnose routing with traces — Traces.