Docs › Errors

Errors

SpiderGate uses conventional HTTP status codes and an OpenAI-style error object. Because the gateway already fails over across providers, a sustained error usually points at your request or account — not a single provider being down.

Error object

{
  "error": {
    "type": "invalid_request_error",
    "code": "model_not_found",
    "message": "Unknown model or alias: 'spideriq/fastt'"
  }
}

Status codes

Code	`error.code`	When	Resolution
`400`	`invalid_request_error`	Malformed body — e.g. missing `messages`, bad `response_format`	Check the request against Chat Completions; `messages` and `model` are required.
`401`	`invalid_api_key`	Missing / malformed / rotated key	Send `Authorization: Bearer <key>`; rotate-check the key.
`402`	`insufficient_quota`	Out of credit, or `max_cost_usd` below the request's cost	Top up credit, or raise `spidergate_options.max_cost_usd`.
`404`	`model_not_found`	`model` isn't a known alias or model id	Use a valid alias (Task Aliases) or id (Models).
`429`	`rate_limit_exceeded`	Too many requests for your key's quota	Exponential backoff + retry. Persistent 429 = your quota, since SpiderGate already load-balances providers.
`500`	`internal_error`	Transient gateway fault	Retry with backoff; if it persists, check the status page.
`502`	`all_providers_failed`	Every model in the alias chain failed	Retry; widen the chain with `spidergate_options.fallback_models`.

Handling pattern

from openai import OpenAI, APIStatusError

client = OpenAI(api_key=os.environ["SPIDERGATE_API_KEY"],
                base_url="https://spideriq.ai/api/gate/v1")
try:
    resp = client.chat.completions.create(model="spideriq/fast", messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        backoff_and_retry()          # transient
    elif e.status_code == 402:
        raise RuntimeError("Top up SpiderGate credit")   # not retryable
    else:
        raise

Retry 429 / 500 / 502 with backoff. Never retry 400 / 401 / 402 / 404 — fix the request or account first.

Last updated July 19, 2026