Bring your own keys. Share a free one with the pool if you want. [ GET YOUR VAULT ]

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` | Your workspace holds no key that can serve the model | `no_access`
`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, the access check could not run, or no key for a required provider | `service_unavailable`, `capability_unavailable`, `no_openai_key`, `no_embeddings_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 — no key for this model (no_access)

SpiderGate runs on keys your workspace brings. A request is served from your workspace's own keys, then from keys a connected company shares with you, then from the community pool of free keys if your workspace shares at least one active free key of its own. When none of those can serve the model you named, the gateway refuses with 403 and code: "no_access". It applies to chat completions, Responses, the Playground and media generation.

{
  "error": {
    "code": "no_access",
    "type": "permission_error",
    "message": "Your workspace has no key that can serve 'spideriq/chat'. Add a key for mistral or openrouter in SpiderGate setup: https://app.spideriq.ai/dashboard/gate/setup",
    "suggested_action": "Add an API key for mistral or openrouter, then send the request again.",
    "suggested_url": "https://app.spideriq.ai/dashboard/gate/setup",
    "model": "spideriq/chat",
    "providers": ["mistral", "openrouter"],
    "tenant_access": "locked",
    "next_step": "add_key",
    "setup_url": "https://app.spideriq.ai/dashboard/gate/setup"
  }
}
::table
Field | Meaning
`providers` | The providers whose key would unlock this model. Empty when no single provider would.
`tenant_access` | `locked` — no key reaches it. `lease_only` — the model is reached only through its own sign-in app, never through chat.
`next_step` | Always `add_key`.
`setup_url` | Where to add the key. The same link is in `suggested_url`.

Errors:

Code

Trigger

Resolution

no_access

No own, connected-company or pool key can serve the model

Add a key for one of the providers in providers, then send the request again

Add a key for one of the named providers and send the request again — Set up SpiderGate with your own keys walks you through it. To see which ready-made names your keys can serve before you call one, read Use recipes on your own keys.

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, or no_embeddings_key on embeddings). For the latter, add an sk-… key via the contributor invite on The Key Vault.

capability_unavailable means SpiderGate could not check which models your workspace may use, so it refused rather than guess. Nothing is wrong with your keys; send the request again shortly.

Routing failures vs. errors

A single upstream model being busy or erroring is usually not an error you see — SpiderGate retries on the alias's pool and serves from another slot. You get a 5xx when the alias's pool cannot serve and the alias has no hand-over to another alias, or that alias cannot serve either. The X-SpiderGate-Fallback-From header is not a failure signal: it is sent whenever a slot other than slot 0 served. 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.