API errors and safe retries

Start with the HTTP status and the structured error object. Do not retry every failure with the same request.

Response or state	Meaning	Client action
HTTP `400`	Invalid model, image data, field, size, ratio, or candidate count	Fix the request; do not retry unchanged
HTTP `401`	Missing or invalid API key	Replace or rotate the key
HTTP `403` with `insufficient_user_quota`	Valid key, insufficient balance or unavailable account access	Check funding, account, and group access
HTTP `409`	An `Idempotency-Key` was reused with a different normalized request	Reuse the original body or create a new key
HTTP `413`	Decompressed request body exceeds a current ingress limit	Reduce the source image and total JSON body; do not retry unchanged
HTTP `404` on task retrieval	Missing task or a task owned by another account	Verify the task ID and Bearer key
HTTP `429`	Selected upstream rate, quota, spend, or model-capacity response	Honor `Retry-After` when present, then back off with jitter
HTTP `500`	Server could not complete the request	Retry a limited number of times with bounded backoff
Task `failed`	Background execution ended unsuccessfully	Read `error.code`, `message`, and `retryable`
Task `expired`	A successful image result passed its 24-hour window	Create a new task only if the output is still required

A typical error response has this shape:

{
  "error": {
    "message": "Insufficient balance for this request",
    "type": "new_api_error",
    "param": "",
    "code": "insufficient_user_quota"
  }
}

Prevent common validation failures

Omit imageSize for gemini-2.5-flash-image.
Lite accepts an omitted size or uppercase 1K.
Flash and Pro accept an omitted size for 1K, or uppercase 1K, 2K, or 4K.
Omit candidateCount or set it to 1.
Use raw Base64 in inlineData.data; do not include a data URL prefix.
Match inlineData.mimeType to the source bytes.

Synchronous requests use their provider-shaped source-image fields. Unified editing accepts 1–16 PNG, JPEG, or WebP images, at most 20 MiB decoded per file and 64 MiB in total. Treat HTTP 413 as a request-size failure, not a transient server error.

Prevent GPT Image validation failures

Use low, medium, high, or auto for either GPT Image route; the selected upstream determines the effect.
Set size explicitly to 1024x1024, 2048x2048, or 3840x2160.
Omit n or use 1.
Send Edit as multipart/form-data with one image file and a prompt.
Submit asynchronous generation or editing to /v1/images/tasks with action=generate|edit.
For action=edit, provide 1–16 input_images items with matching MIME.
Keep reverse-image requests at n=1; omit masks, transparency, output-format controls, and partial-image streaming.
Parse GPT task output from native result.data[].b64_json; parse Nano Banana from native result.candidates[].content.parts[].inlineData.

Treat an async submit timeout as unknown

Before submitting, create an Idempotency-Key of at most 255 bytes and persist it with the application job. A retry with the same body returns the original task instead of creating duplicate billable work. Reusing the key with another body returns HTTP 409. There is no task-list query for recovering a lost ID, so persist task_id as soon as HTTP 202 returns.

429 is not a fixed gateway RPM limit

The documented Nano Banana routes do not have a fixed platform-side RPM cap; the gateway access layer supports at least 5,000 API requests per minute. A 429 on these routes should be handled as an official-upstream rate or capacity response. Google may enforce RPM, images per minute, spend, project tier, or model-capacity limits independently of the gateway. The 5,000 RPM figure describes request ingress, not 5,000 completed images per minute. See traffic capacity and availability for the complete scope. The 5,000 RPM and 98% statements are scoped to the documented Nano Banana gateway routes. No separate GPT Image gateway RPM or availability objective is currently published. GPT Image clients should still honor Retry-After, use bounded backoff with jitter, and stop after a deadline.

Bound retry behavior

Retry only transient rate-limit or server failures. Set a maximum attempt count or deadline, add random jitter, and stop retrying when the response indicates a validation, credential, balance, or ownership problem.

Authenticate correctly

Create, store, and rotate a YingTu development key.

Use bounded polling

Implement Retry-After, jitter, deadline, and terminal-state handling.

Plan traffic capacity

Separate gateway RPM, upstream capacity, and the availability objective.

Check model parameters

Open the selected model’s exact size and ratio contract.

Check GPT Image parameters

Choose Web or VIP and send only its supported fields.

Contact API support

Send a redacted report with responseId or task_id when documented actions fail.

​Prevent common validation failures

​Prevent GPT Image validation failures

​Treat an async submit timeout as unknown

​429 is not a fixed gateway RPM limit

​Bound retry behavior