Skip to main content
Each chat endpoint returns errors in the same shape as the API standard it is compatible with (OpenAI, Anthropic, or Gemini). Every error response also includes an 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 error type / 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 HTTP 400 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 structured error.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, inspect credits.charged and 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 any request_id or X-Request-Id you 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 HTTP 400 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.
Ordinary child-safe scenes such as family, classroom, sports, and art prompts are not blocked by this targeted preflight rule. Requests that pass preflight remain subject to each model’s general safety policy.

Personal MCP

Personal MCP tool failures use isError and structuredContent; uncertain writes require checking the existing execution before another attempt. See Personal MCP error handling and the tool reference.