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`	Usage limit reached for the member or dedicated key on that 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 usage limits:

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.

Usage limits (402)

Usage limits apply per member or dedicated API key × provider instance. Cost limits and separate input/output token limits are enforced independently; reaching any configured limit blocks further requests:

Inherit API keys (default) count towards the creator’s personal usage limits.
Dedicated API keys have separate cost limits and token limits.
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.
A member or dedicated key without configured limits on a provider has no optional cost or token cap there. Routing policy, technical API limits and upstream provider quotas still apply.

Org admins configure optional BYOK caps on Usage limits.

Usage limits are optional in both deployment modes. An empty cost or token limit adds no cap for that unit; configured limits are always enforced, and an explicit zero 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, usage limits, routing policy, or configuration.
Retry 503 (service_unavailable) with backoff: the disruption is usually brief.
500 may be retried sparingly.