X-Request-Id header, and returns only the information you need to
debug your request.
OpenAI — /v1/chat/completions (and image/video endpoints)
Anthropic — /v1/messages
Gemini — /v1beta/models/{model}:generateContent
Status mapping
The errortype / status is derived from the HTTP status:
Fix authentication, credit or rate-limit errors
When a known request is rejected with HTTP
429, retry a limited number of
times with jittered exponential backoff. For example, draw the next wait at
random between 0 and min(30_000, 1_000 * 2 ** attempt) milliseconds. If the
response specifies a later X-RateLimit-Reset, also wait until that time.
Honor your application’s time budget. This retry rule applies to a confirmed
rejection and to safe reads. A timeout during media submission requires the
recovery steps below.
Model parameter rejections
When a model does not accept a value in your request, the endpoint returns HTTP400 with the model’s own explanation. Reasoning settings use the code invalid_reasoning_effort, and the message lists the values that model accepts, so the request can be corrected without guessing. Each model’s accepted reasoning levels, its default and whether reasoning can be disabled are published in GET /v1/models under capability_metadata.reasoning.
A 504 indicates that a request exceeded its time budget. A 502 indicates that model execution did not produce a usable response. Read the structured error before changing request parameters.
Media generation errors and retries
For image and video generation, use the structurederror.code and the task’s
status (task.status in your client) to decide what to display and whether to retry.
Only suggest content changes for an explicit policy code or a clear content-policy
refusal. A message merely mentioning
safety, or HTTP 502 alone, is not evidence
of a policy violation. If an asynchronous task is still pending or processing,
continue querying /v1/tasks/{task_id} with the same task_id; do not submit a
duplicate generation request.
- With a known
task_id, follow task status and resume polling that task after a client timeout. Once it finishes, inspectcredits.chargedand the billing policy before deciding whether to submit again. - If submission timed out before you received a
task_id, check task history before sending another create request. Keep anyrequest_idorX-Request-Idyou received for support. Some video tools have their own documented request correlation option. - Treat a callback as a notification. Confirm its task ID and terminal result with an authenticated task lookup before taking an irreversible action. See webhooks.
Minor-sensitive media prompts
Image and video requests are rejected with HTTP400 and code
content_policy when a prompt clearly combines a minor with exposure or
emphasis of sensitive body areas, or with explicit sexual or nudity content.
This check happens before task creation and credit reservation, so no credits
are charged.
Personal MCP
Personal MCP tool failures useisError and structuredContent; uncertain writes require checking the existing execution before another attempt. See Personal MCP error handling and the tool reference.