خطاها

The request body or query parameters are invalid. Check the error.code and error.message fields for details. Codes the gateway emits at 400:

• BAD_REQUEST: generic malformed JSON / missing required field.
• INVALID_TOOLS: the tools array, plugins field, or model's :online suffix uses an unsupported shape. The response names the offender and links to the supported form. See the dedicated InvalidTools response below for the three triggers and migration hints.
• UNSUPPORTED_TOOL: a built-in tool (file_search, code_interpreter, computer_use, mcp) whose pricing dimension is not yet wired into the gateway hold estimator.
• INVALID_AUDIO_FORMAT: input_audio.format value is not in the supported set. The envelope lists every supported codec name. The gateway accepts both short names (wav, webm) and full MIME aliases (audio/wav, audio/webm); anything else fails fast at admission. See API guide §8b.
• AUDIO_NOT_SUPPORTED_ON_RESPONSES: input_audio content part sent to POST /v1/responses. The Responses API has no audio content type today; resend to POST /v1/chat/completions instead.

Returned when the tools array, plugins field, or model :online suffix uses a shape the gateway does not support. The three triggers documented today:

• "model":"…:online": legacy variant; use tools:[{"type":"web_search"}].
• "plugins":[{"id":"web"}]: legacy plugin form; same migration.
• "tools":[{"type":"<internal>:…"}]: internal namespace; drop the prefix and use the short name.

The error message names the offender and includes a migration hint. The hold has NOT been placed (no charge).

The image bytes could not be decoded (HEIC, AVIF, partial bytes, non-image content). The classifier requires JPEG, PNG, WebP, or GIF input. Re-encode the image and resend with a fresh Idempotency-Key. The hold has been released.

Authentication failed. Either the Authorization header is missing, the key format is invalid, or the key doesn't match any active account.

The requested resource was not found. Either the ID is wrong or it belongs to a different account.

Idempotency key conflict: you sent the same Idempotency-Key with a different request body.

Too many requests. Back off and retry after a short delay. Check the Retry-After header for guidance.

Your HTTP client cancelled the request before the gateway finished. No charge: the hold has been released. The most common cause is a 30 s default client timeout against a model whose p95 latency is 45-60 s; bump your client timeout to 120 s.

Retries with the same Idempotency-Key will replay this 499 forever (the prior outcome is "you cancelled"). For an actual re-attempt, mint a fresh Idempotency-Key. See docs/CUSTOMER_ERROR_HANDLING.md §3 for the full contract.

Unexpected server error. Please retry with exponential backoff. If the issue persists, contact your admin.

The upstream AI provider is temporarily unavailable. Retry with exponential backoff (1s, 2s, 4s) using the same Idempotency-Key: if the upstream actually completed the work and only the response failed, the gateway replays the cached success without a second charge. Holds are released automatically on upstream failures.

The gateway's 120 s upstream deadline elapsed before the upstream provider produced a response. Retry with the same Idempotency-Key so a delayed-but-eventually-successful upstream call can be replayed instead of re-charged. Consider switching to a faster model or capping max_tokens if this recurs.