Errors & limits

Errors use an OpenAI-style envelope:


{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

HTTP status matrix

Status	`code`	When
`401`	`invalid_api_key`	Missing, malformed, or revoked API key
`402`	`insufficient_quota`	Budget exhausted for the subject × provider instance (money and/or token caps). Returned on the next gated attempt after an overshooting call.
`403`	`account_disabled`	Account disabled or frozen; inference not allowed
`403`	`insufficient_permissions`	Plan, billable seat, or feature not enabled
`403`	`provider_not_permitted`	Model provider below key minimum execution environment
`429`	`rate_limit_exceeded`	Per-minute request limit or concurrent stream cap
`400`	`invalid_request_error`	Invalid JSON or unsupported parameters
`400`	`model_not_found`	Unknown or disabled model ID
`500`	`internal_error`	Unexpected server error
`503`	`service_unavailable`	Temporary service disruption; try again shortly

Rate limits

Per-context limits apply to keep the service stable:

Requests per minute — maximum completion and model-list requests in a rolling window.
Concurrent streaming — maximum in-flight streaming completions at once.

When a limit is exceeded, the API returns 429 with rate_limit_exceeded. Retry after a short delay; respect Retry-After when the response includes it.

Budget (402)

Budgets gate completions per Budget subject × provider instance in money and/or separate input/output token units (first exhausted configured unit wins):

Inherit API keys (default) debit the creator’s user Budgets — same pool as chat for that member.
Dedicated API keys are their own Budget subjects; System Gateway money comes from the org API allocation.
An in-flight call that overshoots still returns 200 with full usage; the client learns exhaustion on the next gated attempt via 402 insufficient_quota.
BYOK providers with no Budget row are uncapped by Steinkauz (upstream provider quotas may still apply). System Gateway on Gateway plans always requires a money Budget row.

Org admins configure the System Gateway pool and optional BYOK caps on Settings → Budgets.

CORS

API Access is intended for server-to-server use. Do not expose API keys in front-end code or call the API directly from a browser.

Retries

Retry 429 with exponential backoff and respect Retry-After when present.
Do not retry 401, 402, or 403 without fixing credentials, budget, seat status, or configuration.
Retry 503 (service_unavailable) with backoff — the disruption is usually brief.
500 may be retried sparingly.