Error Codes

Platform-wide error codes are documented on this page. Resource-specific error codes remain on the relevant Reference page.

Common error codes

HTTP	Common code / type	Description
400	`invalid_request_error`	Invalid request parameters or request structure.
400	`missing_required_field`	A required field is missing.
400	`invalid_field_value`	A field value is invalid.
400	`invalid_range`	A field value is outside the allowed range.
400	`unsupported_response_format`	The requested output format is not supported.
400	`unsupported_feature_for_model`	The selected model does not support this capability.
400	`invalid_url`	The URL format is invalid.
400 / 403	`url_not_allowed`	The URL was rejected by security rules.
401	`authentication_error`	Authentication failed; the framework supports this status.
403	`permission_error`	The API Key is missing or invalid, permission is insufficient, or a security policy blocked the request; the current gateway may return 403.
402	`billing_error` / `insufficient_credits`	Billing failed or the account has insufficient credits.
429	`rate_limit_error` / `rate_limit_exceeded`	The request rate limit was exceeded.
429	`concurrency_limit_exceeded`	The concurrency limit was exceeded.
409	`conflict_error`	A resource conflict occurred.
404	`not_found_error`	Generic resource-not-found type; resource-specific codes remain on endpoint pages.
403	`safety_guardrail_blocked`	The request was blocked by a safety policy.
500 / 502 / 503 / 504	`internal` / `upstream` / `service` / `timeout`	Server, upstream, unavailable service, or timeout failure.

Error structure categories

Error structure	Documentation location	Applies to
Common synchronous HTTP error	Resources → Error Codes	Ordinary JSON errors returned before a response begins.
SSE `error` event	Streaming section of Single-speaker Speech	In-stream failures after an SSE response has started.
Asynchronous task failure	Get Task	A task was created successfully but ultimately entered `FAILED`.
Raw PCM interrupted mid-stream	Streaming section of Single-speaker Speech	No JSON error body; the connection ends early.

Common synchronous HTTP error structure

{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "param": null,
    "code": "error_code"
  }
}

Common synchronous HTTP errors follow this structure. The exact error.code and parameters depend on the endpoint documentation and the actual response.