Errors and recovery
Keep request IDs and recover uncertain work without duplicate charges.
AI errors use the OpenAI-compatible envelope:
{"error":{"message":"Request rejected","type":"invalid_request_error","param":null,"code":"invalid_request"}}| Status | Action |
|---|---|
| 400 | Correct the request, model constraints or content type before a new logical request |
| 401 | Replace an invalid, revoked or expired credential |
| 403 | Check scope, product activation, project/tenant access and policy |
| 409 | Reuse of a key with a different request: restore the original payload |
| 413 | Reduce request/upload size |
| 429 | Honor Retry-After; check traffic quota and spend/credit admission |
| 5xx or interrupted stream | Inspect the task; the provider may have accepted paid work |
Capture X-Request-Id, X-AI-Request-Id and the original Idempotency-Key. If a retry is appropriate, send the identical request and key. Never regenerate the key inside a retry loop. A completed replay does not submit or charge a second generation.
reconciliation_required means Cloud lacks sufficient verified evidence to settle the outcome. Billing remains pending; no funds are held, and it is not a zero-cost result. Preserve identifiers for support and continue reading the task rather than submitting replacement work.
A response's text or partial stream is not proof of finalized billing. See pricing.
If the playground cannot load models and shows ai_service_unavailable, the
deployment's AI service needs operator activation or configuration. Enabling the
project alone does not start the gateway's AI runtime. gateway_unavailable
means a console transport could not connect to its upstream service; an operator
should check gateway/container health and the private service URLs. Model reads
are free and do not create a generation job. Retaining an idempotency key matters
when a submitted generation has an uncertain outcome.