Errors & limits

Errors use an OpenAI-style envelope:


{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "param": null,
    "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 or feature not enabled
`403`	`provider_not_permitted`	Model provider below key minimum execution environment
`403`	`routing_policy_violation`	Effective data class is not allowed on that provider environment
`429`	`rate_limit_exceeded`	Per-minute request limit or concurrent stream cap
`400`	`invalid_request_error`	Invalid JSON or unsupported parameters
`404`	`model_not_found`	Unknown, disabled, or upstream-missing model ID
`400`	`unsupported_model_capability`	The selected provider adapter does not implement the requested operation
`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, with the same caps as chat for that member.
Dedicated API keys are their own Budget subjects with optional BYOK / token caps.
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.
Providers with no Budget row are uncapped by Steinkauz AI (upstream provider quotas may still apply).

Org admins configure 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, routing policy, or configuration.
Retry 503 (service_unavailable) with backoff: the disruption is usually brief.
500 may be retried sparingly.