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`	Organization access 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 connection or model does not support the requested operation
`413`	`invalid_request_error`	Request exceeds the supported size limit
`499`	`aborted`	The caller cancelled execution; no successful partial result is returned
`503`	`provider_error`	Provider failure, timeout or invalid response
`500`	`internal_error`	Unexpected server error
`503`	`service_unavailable`	Temporary service disruption; try again shortly

Rate limits

Technical API limits apply separately from commercial Cloud usage allowances and optional Budgets:

Cloud requests per minute: by default, 30 authenticated API requests per API key in a 60-second window, including model listing and inference endpoints.
Cloud concurrent streaming: by default, five in-flight streams per user, shared across that user’s API keys and organizations.

Private deployments default to unlimited request rate, concurrent streams and active API-key count, and have no commercial Cloud request/storage allowance. Deployment operators can configure these limits. API access displays the effective limits for your deployment.

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, against that member’s optional caps.
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 without a configured Budget have no optional Budget cap. Routing policy, technical API limits and upstream provider quotas still apply.

Org admins configure optional BYOK caps on Budgets.

Budgets are optional in both deployment modes. An undefined budget or empty cap adds no budget restriction; defined caps are always enforced, and an explicit zero cap is exhausted. Usage is recorded in either case. Provider quotas, authentication, tenant isolation and routing policy still apply.

Embedding and transcription bounds

Embedding JSON has a 48 MiB transport ceiling and accepts up to 2,048 text inputs per request. Audio files have a 25 MiB transport ceiling plus bounded multipart overhead. Upstream services may impose lower limits. Clients can set deadlines and cancel requests. Only standard text embedding JSON and multipart transcription uploads are supported. Streaming/diarized transcription and custom media JSON fail explicitly.

An upstream failure or policy denial does not switch to another provider automatically. See Text embeddings and Audio transcription for supported formats and timing.

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.