Errors & Limits

Stable errors, retry rules, and authoritative beta limits.

#Errors

Branch on HTTP status and stable type/code, never message text.

Type	Code	HTTP	Retry?	Action
`authentication_error`	`invalid_api_key`	401	No	Check the project key.
`invalid_request_error`	`invalid_request`	400	No	Correct the request.
`billing_error`	`insufficient_balance`	402	No	Add funds or review the cap.
`rate_limit_error`	`rate_limit_exceeded`	429	Yes	Honor Retry-After; add jitter.
`timeout_error`	`request_timeout`	408/504	Yes	Retry safely with backoff.
`service_unavailable_error`	`service_unavailable`	503	Yes	Retry with backoff.
`invalid_request_error`	`asset_expired`	400/404	No	Create or upload a new Asset.
`internal_error`	`internal_error`	500	Maybe	Record Request ID; retry if safe.

Honor Retry-After and reset headers. Use bounded exponential backoff with jitter.

Operation	Idempotency	Cancellation
Chat/synchronous inference	No key; retries may duplicate work.	Client abort does not prove upstream cancellation.
Media generation	Video supports a key; other media does not document one.	Started work may remain billable.
Jobs	Polls are safe metadata reads.	Cancellation is best effort.
Streaming	A retry creates a new request.	Generated usage may be billed.

Capability	Limit
Project request rate	60/min; burst 20/10 sec
Concurrent inference	10/project
Chat body	8 MiB
Messages	256; 256 KiB each
Requested output	32,768 tokens
Temporary files	1 hour; 100 live/project
Knowledge upload	16 MiB/source
Video input	MP4; 10 MiB; 5 minutes
Audio transcription	20 MiB
Realtime	10 minutes; 1-minute idle; 2 concurrent
Realtime frames	16 KiB text; 64 KiB audio
Assets	Temporary; project-scoped
Jobs	Project-scoped; terminal after completion/failure/cancel

All project keys share these limits. GET /v1/limits returns effective policy and spend.