Reference
Errors
Status codes, error codes, and what to do about each.
Failed requests are never charged.
Shape
/v1/systemone and the authentication and rate-limit errors on every /v1
endpoint use one envelope:
{"error": {"code": "bad_labels", "message": "question 'q': choice needs a criteria dict with >=2 labels"}}
/v1/pick reports validation errors as {"detail": "…"}. The Gemini API
endpoints (/v1beta) return Google’s error shape.
Codes
| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, unknown or revoked key. |
| 402 | insufficient_credit | The account’s free decisions or credit are used up. |
| 413 | state_too_long | The state exceeds the 49,152-token context. |
| 422 | no_questions, bad_question, bad_type, bad_labels, missing_state, bad_image, bad_request | The request body is invalid; the message says which part. |
| 503 | overloaded | At capacity. Retry after the Retry-After header. |
| 502 | backend_unavailable | The model backend is down. |
| 504 | timeout | The model did not answer in time. |
Retrying
Retry 503, 502 and 504 with exponential backoff, honouring
Retry-After when it is present. Don’t retry 4xx responses without changing
the request: they fail the same way every time.