Troubleshooting

Record these details first

• Time and time zone
• Gateway domain
• Client and exact version
• Model alias
• HTTP status and structured error code
• x-request-id or request-id
• Whether the request was streaming

Common failures

• 401: the key is missing, invalid, disabled, expired, or the owning service account is disabled.
• 403: the key is not allowed to use the requested model or operation.
• 402 quota_exceeded: quota or wallet balance is exhausted; resolve capacity before retrying.
• 413: the request body exceeds the endpoint limit; reduce its size and do not retry the unchanged request. Retain x-request-id for support.
• 429 rate_limited: the request rate limit was reached; retry with bounded backoff.
• 503 model_not_available: no currently published and safe route can serve the alias.
• 5xx: retain the Request ID. For text requests, check the error before bounded backoff; never retry forever. Do not automatically retry image requests after a timeout, image_result_unknown or invalid_image_result. Locate the request in Usage or ask your administrator first; an empty list is not proof of no upstream work. Resubmitting can generate and charge again, and cannot recover the previous image.

Streaming

Receiving text deltas is not enough to declare success. Require the protocol terminal event. Treat cancellation, EOF without a terminal event, malformed SSE, or a failure event as incomplete and do not duplicate downstream side effects.

Contact support safely

Provide the diagnostic fields above, but never send a complete API key, Authorization header, provider credential, cookie, sensitive business data, or full prompt/response.

Not currently available

• Embeddings, Files, Batch, Audio, and Realtime
• Assistants API and WebSocket transport
• Bedrock, Vertex, and Gemini native client protocols
• Server-hosted tools; client tools remain the client's responsibility