Docs
Errors and rate limits
Errors use the OpenAI shape:
{ "error": { "message": "…", "type": "invalid_request_error", "param": null, "code": "input_url_rejected" } }
| HTTP | type | code |
|---|---|---|
| 400 | invalid_request_error | invalid_request, unsupported_parameter, unsupported_media, input_url_rejected, content_blocked, duration_exceeded, data_class_not_allowed |
| 401 | authentication_error | invalid_api_key |
| 402 | insufficient_quota | insufficient_balance: top up in the console |
| 403 | permission_error | account_not_active, scope_missing, kyb_required |
| 404 | not_found_error | model_not_found, job_not_found |
| 409 | invalid_request_error | idempotency_key_reused |
| 413 | invalid_request_error | file_too_large: use the batch endpoint |
| 429 | rate_limit_error | rate_limited, queue_full, with Retry-After |
| 503 | service_unavailable | metering_unavailable, no_capacity |
503 metering_unavailable means our metering service is unreachable and we refuse work rather than run it uncounted. Retry with backoff.
Rate limits
Responses carry x-ratelimit-* headers. On 429 or 503, wait for Retry-After seconds. The OpenAI SDKs do this automatically. Use an Idempotency-Key so retries never create duplicate jobs.