Usage

Errors

Standard HTTP status codes, a machine-readable code in the body, never content. Two formats — because the inference API speaks the OpenAI format every SDK understands.

Two formats

The path tells you which surface answers: OpenAI endpoints answer in the OpenAI error format, the App API with our envelope.

Inference API (OpenAI format)

{
  "error": {
    "message": "Budget has been exceeded! Current cost: 14.02, Max budget: 14.0",
    "type": "budget_exceeded",
    "code": "429"
  }
}

The format the official OpenAI SDKs map to exceptions — type and code come from the gateway.

App API (envelope)

{
  "error": {
    "code": "scope_missing",
    "message": "This API key does not carry the scope this endpoint requires.",
    "request_id": "3f6c1c9e-0a4b-4c3e-9b0e-6a1d2f8e4b21"
  }
}

A fixed format with a request_id on every answer — quote it to support and we find the request without its content.

Error codes

Status	Code	Surface	Meaning
401	unauthorized	both	No, invalid or revoked API key.
401	key_expired	App API	The key has expired — create a new one.
400	invalid_request_error	inference	Invalid request (missing required fields, unknown parameter, body too large).
400	invalid_body	App API	The request body does not match the endpoint's schema.
403	scope_missing	App API	The key does not carry the scope this endpoint requires.
403	browser_request_rejected	App API	The request looks like a browser (Origin, fetch metadata or session cookie).
403	academy_only	App API	This account only has access to the Akademie, not the platform.
404	model_not_found	inference	Unknown model id, or a model this key may not address.
404	not_found	App API	The resource does not exist or is not shared with this key — both answer 404.
429	rate_limit_error	both	Too many requests in the window; retry-after names the wait.
429	budget_exceeded	both	The organisation's usage quota is exhausted — no retry helps until the window resets.
500	internal_error	both	Internal error; retry, and on repetition give the request_id to support.
503	service_unavailable	inference	The model is temporarily unreachable — retry with backoff.

Handling errors

Retry 429 and 503 with exponential backoff; retry-after is the lower bound.
budget_exceeded is also 429 but not a retry case: the quota resets with the window, not by waiting seconds.
A 404 does not distinguish “does not exist” from “not shared with you” — deliberately, so the API never reveals the existence of foreign resources.
The App API's request_id identifies the request without its content; our logs never contain prompts or completions.