Errors

The native API uses conventional HTTP status codes to signal success and failure.

Status	When
`401`	Missing, invalid, or inactive API key.
`402`	Insufficient funds to reserve the job’s price.
`403`	API key lacks permission for the requested model.
`404`	`GET /jobs/{job_id}` for an unknown id or a job owned by another account.
`422`	Validation failure — unfetchable URL or oversized input.
`502`	Upstream storage failure while ingesting inputs.
`503`	The project or the requested model is paused — try again later.

Handling tips

401 — Authentication

Verify the Authorization: Bearer <key> header and that the key is active. See Authentication.

402 — Insufficient funds

Check GET /balance. The available amount must cover the job’s reserved price.

403 — Model permission

The key isn’t scoped for the requested model. Grant access in the web panel or use a different key.

422 — Validation

Common causes: an input_images_urls entry that can’t be fetched, total input size over 200 MB, or an aspect_ratio the model doesn’t support.

503 — Paused

Transient — the project or model is paused. Retry later, ideally with the same Idempotency-Key.

The Gemini-compatible endpoint returns errors in Google’s envelope so the google-genai SDK surfaces them as errors.APIError:

{
  "error": {
    "code": 403,
    "message": "API key missing permission for gemini-3-pro-image",
    "status": "PERMISSION_DENIED"
  }
}

HTTP	`status`	When
`400`	`INVALID_ARGUMENT`	Invalid API key, malformed request, unsupported `imageSize`, or a request body over 200 MB.
`403`	`PERMISSION_DENIED`	Missing API key, or the key lacks permission for the model.
`404`	`NOT_FOUND`	Unknown model id.
`503`	`UNAVAILABLE`	Project or model paused, or no capacity — retry later.
`504`	`DEADLINE_EXCEEDED`	The upstream request timed out.
`500`	`INTERNAL`	Unexpected server error.

A prompt blocked for safety is not an error: it returns 200 with finishReason: IMAGE_SAFETY and no image, and is not charged.