Reference

Errors

Every error the gateway and published endpoints return, and what to do about each.

All errors have the same body, compatible with OpenAI clients:

{
  "error": {
    "message": "Monthly budget of $50.00 reached for this key.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

type is the category below. code is the same or more specific (for example invalid_model_output). Messages for provider and network failures are deliberately generic. The X-Scalaix-Request-Id header identifies the request; include it when you contact support.

Status	`type`	Meaning	What to do
400	`invalid_request`	The request body or a parameter isn't valid.	Fix the request. Don't retry.
401	`invalid_api_key`	The key is missing, unknown, revoked or expired.	Check the `Authorization` header and the key in the console.
402	`insufficient_quota`	The team is out of credits, or the key's monthly budget can't cover the request's worst case.	Buy credits in the console (account menu → Billing), raise the key's budget, or set `max_tokens`.
403	`forbidden`	The key's rules don't allow this model, collection, origin, IP range or mode.	Change the request or the key's rules.
404	`not_found`	Unknown model, project, collection, endpoint or version.	Check the URL and `?version=`.
413	`invalid_request`	The body is too big: over 10 MB for chat, over 1 MB for endpoint calls.	Send less: trim history, or pass large documents another way.
422	`invalid_inputs`	Endpoint inputs don't match the variables. The message has the path.	Fix the inputs. Don't retry.
429	`rate_limited`	Over the key's requests per minute.	Wait `Retry-After` seconds, then retry.
501	`not_implemented`	The feature isn't available yet (for example `file` variables).	Use another approach for now.
502	`upstream_error`	The provider failed and no fallback model answered.	Retry with backoff; add `fallback_models`.
502	`invalid_model_output` (code)	The model's JSON didn't match the schema after one repair.	Simplify the schema, add descriptions, or use a stronger model.
504	`timeout`	The provider didn't answer in time.	Retry; lower `max_tokens`; add fallback models.

Retrying

Retry 429, 502 and 504 with exponential backoff and jitter. Respect Retry-After on 429. Don't retry 400, 401, 403, 404 or 422: the same request fails again.

The OpenAI SDKs retry 429 and 5xx automatically (twice by default). For endpoint calls, a small loop is enough:

import random, time, requests

def call(url, key, inputs, attempts=4):
    for i in range(attempts):
        r = requests.post(url, headers={"Authorization": f"Bearer {key}"}, json={"inputs": inputs}, timeout=90)
        if r.status_code not in (429, 502, 504):
            r.raise_for_status()
            return r.json()
        wait = float(r.headers.get("retry-after", 2 ** i)) + random.random()
        time.sleep(wait)
    r.raise_for_status()