Diagnose image API errors before resubmitting
Separate connectivity, authentication, input, credit, policy and upstream errors; HTTP success alone does not establish task success.
Technical review:
First locate the failing layer
If DNS, TCP or TLS fails before any HTTP response, there is no HTTP status to interpret. Capture a timestamp, hostname and sanitized network error; do not call it a model failure. Once a response arrives, record the HTTP status, error.code, request ID and task ID if present. For asynchronous work, inspect task status as well. Avoid sending keys, raw reference files, private prompts or unredacted customer details in a support ticket.
400, 401, 402 and 403: inspect the request and account
400 usually requires inspecting the error detail and correcting the payload: unknown model, invalid size, unsupported fields or an invalid reference file are different problems. For 401, confirm the bearer key is present and valid without printing it. For 402, check available balance and any reservation or budget controls. For 403, check model and route permissions; setting a restricted route name in JSON does not grant access. Retrying the same invalid configuration is not a fix.
429, 451 and 5xx: do not collapse them into one cause
429 needs rate-limit investigation and a bounded retry policy. A 451 response in an image workflow needs its error detail and policy context reviewed; it should not be reclassified as an image-format error or retried in an attempt to bypass the restriction. 5xx can indicate service, upstream, capacity or timeout failures, but the status alone does not identify which component failed. Preserve the existing task and request IDs and check the final state before creating new work.
Prepare a minimal diagnostic record
A useful report includes UTC time, endpoint, public model ID, requested route, output size and quality, reference count, HTTP status, error code, request ID and task state. State whether it was submission or polling, whether a result was ever received, and whether the problem reproduces with one authorized non-sensitive reference. This is enough to start investigation without sharing a secret. A successful GET /healthz only tests that health endpoint, not account permissions or a full generation.
Model-specific parameters
Public configuration snapshot; not live availability. Follow each model page for its parameters, supported routes and reference limits.
- Gemini 3.1 Flash Lite Image
google/gemini-3.1-flash-lite-image - Gemini 3.1 Flash Image Preview
google/gemini-3.1-flash-image-preview - GPT Image 2
openai/gpt-image-2