GPT Image 2.5 API Errors: Build a Retry Matrix

Editorial owner: Genflow Editorial · report a factual correction
Research and product-source review completed: September 10, 2026

Creation method: automated tools assisted source discovery, drafting, link checks and originality screening; Genflow Editorial reviewed the current primary sources, product boundary, claims and final copy.

An image request that fails is not automatically a request that should run again. A validation error needs a corrected payload. A rate limit needs pacing. A moderation block needs a safe product response and perhaps changed user input. A network timeout may leave the outcome unknown. Put each failure into a named lane before your worker retries it. Use an Image Request Recovery Ledger to preserve the request, attempt, cost and owner evidence.

This guide covers the upstream gpt-image-2.5-flare and gpt-image-2.5-sunburst models. At the Genflow release revision reviewed here, the product exposes GPT Image 2, not the GPT Image 2.5 identifiers. The method is a production design reference, not an announcement that Flare or Sunburst is selectable in Genflow.

The five-lane retry answer

Route every failure into one of five actions:

1. Fix before retry: invalid request, unsupported setting or user-correctable image-generation error.
2. Wait and retry: a confirmed transient rate/ramp-limit or server failure, with bounded exponential backoff and jitter.
3. Reconcile first: timeout, dropped connection or any ambiguous submission where the server may have accepted work.
4. Human review: moderation block, repeated quality failure, policy-sensitive input or a request whose safe rewrite would change meaning.
5. Stop or defer until state changes: invalid authentication, unavailable entitlement, credit/spend/usage exhaustion, cancelled job or exceeded retry budget.

Do not write retry: true beside an entire HTTP class. The current OpenAI image generation guide and error-code guide distinguish transient rate/server pressure from credit, spend, usage, quota and user-correctable image errors. Route from the stable error code and response body, not status 429 alone.

Separate the job from the attempt

A business job is the requested asset. An application attempt is one decision to call the provider. A transport submission is each actual HTTP submission, including an automatic SDK retry. They need different identifiers when the SDK can retry underneath the application.

The job ID should remain stable across retries and model escalation. The application-attempt ID should change for every retry decision, and every transport submission should be counted beneath it. Store the model, endpoint, request settings, input hashes, prompt version, installed SDK version and retry configuration, timestamps, response status, provider request ID, usage and result checksum.

Choose one retry owner. If the application owns retry policy, disable eligible SDK retries where the installed SDK supports that configuration. If the SDK remains the owner, capture or conservatively budget its transport submissions. Pin and verify the SDK version because defaults can change. An idempotency header that makes an SDK replay eligible is not evidence of documented server-side deduplication for an image request.

This separation prevents three common accounting errors:

• counting five attempts as five customer jobs;
• hiding failed attempts from cost and acceptance-rate reports;
• accepting two late results for one job after an ambiguous retry.

If the current API contract does not explicitly document an idempotency guarantee for your request path, do not assume that resending the same payload is deduplicated. Reconcile the first attempt where possible, or require a human decision when duplicate work would be costly or externally visible.

Build an Image Request Recovery Ledger

Field	Record
Business job	Stable asset request and destination
Attempt	Unique application-attempt ID, parent job ID, SDK version/configuration and actual transport-submission count
Request state	Endpoint, model alias or dated snapshot, prompt version, input hashes, size, quality, format and background
Timing	Queued, submitted, first event, completed or failed timestamps
Provider evidence	HTTP status, stable error code, request ID and permitted coarse moderation details
Outcome certainty	Not submitted, accepted, completed, failed, or unknown
Recovery lane	Fix, wait, reconcile, review or stop
Retry budget	Maximum attempts, maximum elapsed time and spend ceiling
Backoff	Retry number, delay, jitter and capacity signal
Cost	Tokens or charges from every attempt, including partial images and rejected results
Result	Asset checksum, rejection reason, dead-letter record or cancellation
Owner	System, support, safety, engineering, creative or finance owner

The Recovery Ledger is a Genflow Editorial worksheet, not a native feature or reliability guarantee of GPT Image 2.5 or Genflow.

A practical retry matrix

Failure signal	Automatic retry?	Required action
Client validation or HTTP 400	No	Fix the payload, setting, prompt or input before a new attempt
Authentication failure or HTTP 401	No	Stop; verify the key and project; rotate credentials if compromise is suspected
Permission or access failure	No	Verify organization, project, model access and policy; do not loop
Quota or billing exhaustion	No	Stop until capacity or billing state changes
Temporary rate/ramp-limit 429 confirmed by code/body	Bounded	Exponential backoff with jitter; respect Retry-After when present; reduce concurrency
Credit balance, billing, organization/project spend or usage-limit 429	No	Stop or defer until the external account state changes; do not loop
Server failure or HTTP 5xx	Bounded	Back off; retain request ID; stop at the retry/time/spend budget
Network timeout or consumed stream event without a final result	Reconcile first	Mark outcome unknown; look for a completion signal before resubmitting
image_generation_user_error	No blind retry	Change the prompt/input or route to a person based on stable error.code
moderation_blocked	No blind retry	Give a safe generic user response; log permitted coarse context; review or revise safely
Output completes but fails asset gate	No automatic loop	Record rejection and return to creative routing or model evaluation

Use stable codes and SDK exception types for program logic. Human-readable messages may change and should be retained for diagnosis, not parsed as the control plane.

Handle rate limits as queue pressure

The official Flare and Sunburst model pages publish tier-specific limits. Limits can change with the account's usage tier, so read the current model and account state rather than copying a number from a blog into permanent queue logic.

When a stable code/body identifies a temporary rate or ramp limit, exponential backoff with random jitter prevents synchronized workers from retrying together. Respect Retry-After when it is present. A failed request can still consume per-minute capacity, so rapid retries may make recovery slower. The OpenAI rate-limit guidance recommends pacing and backoff rather than repeated immediate submission. A 429 caused by credit, spend or usage exhaustion belongs in the stop/defer lane instead.

Official SDK behavior can add retries below the queue. Count those transport submissions against the same maximum-attempt, elapsed-time and spend budgets. Do not wrap an SDK's automatic retries inside another unbounded application retry loop.

Backoff is only one control. Also set:

• a per-model concurrency ceiling;
• a per-tenant fair-share limit;
• a maximum queued age;
• a job deadline after which the asset is no longer useful;
• a spend ceiling and maximum attempt count;
• an escalation route when premium work cannot wait.

Do not silently switch from Sunburst to Flare, or reduce quality, simply to clear the queue. That changes the production route. Apply the workload's approved Quality–Latency Route Card and record any fallback as a new attempt with its own acceptance gate.

Treat moderation as a decision, not a transient outage

OpenAI states that prompts and generated images are filtered under its content policy. For GPT Image requests, the image-generation guide documents an image_generation_user_error and the stable moderation_blocked code, with optional coarse details such as whether the block occurred at input, output or an unknown stage.

A worker should not repeatedly send the same blocked request. Show the end user a restrained message that does not expose classifier internals. Store only the permitted coarse details for support and analytics. Route a safe, meaning-preserving correction back to the user or an authorized reviewer.

The moderation setting is a product-control choice, not a retry strategy or a way to evade policy. If a product permits a different documented strictness, approve that setting at the application level and still enforce applicable policy and user safeguards.

Reconcile ambiguous outcomes

Timeouts are harder than explicit failures. The client may lose the connection after the service accepted a request. If it immediately creates another attempt, both may complete and both may incur cost.

Represent this state as UNKNOWN, not FAILED. Keep the provider request ID if one was received. Watch the documented response stream, webhook, poll path or application result store for a bounded reconciliation window. Once any streamed output or event has been consumed, do not blindly replay the request; reconcile first. Accept exactly one result against the business job and quarantine late duplicates for review.

If the current endpoint offers no way to look up the outcome and no documented idempotency contract, the retry policy must reflect the ambiguity. Low-cost internal concepts may allow one replacement attempt. Expensive, regulated or externally published work may require a person to decide. Do not invent an API guarantee to make the state machine simpler.

Stream without confusing previews and finals

Both the Responses API image-generation tool and the Image API support partial-image streaming. The guide allows a request for zero to three partial images and notes that the full number may not arrive when generation completes quickly. It also states that each partial image adds 100 image output tokens.

Store partial events as previews tied to the attempt. Do not mark them as accepted assets, run final release automation from them or count them as extra successful outputs. Record the partial-image setting in the ledger so latency experiments include its extra cost.

The final event, asset checksum and review gate should decide completion. If a stream disconnects after previews, the result is ambiguous until the final state is reconciled; a new submission is not an automatic continuation of the old stream.

Count failure economics honestly

For a workload, report at least:

• attempted output slots;
• completed outputs;
• accepted outputs;
• user-correctable failures;
• moderation blocks;
• rate-limit and server retries;
• unknown outcomes and duplicates;
• review and repair time;
• total API and orchestration cost.

API cost should include image input/output usage, 100 additional image output tokens for every requested partial that was delivered, every retry transport submission, late duplicates and rejected finals. When the Responses API is used, also include the mainline model's input and output token usage in addition to image-generation usage. Track orchestration and review labor separately, then define fully loaded cost as API cost plus that labor allocation.

Cost per accepted output is total cost across all attempts divided by accepted outputs. If accepted outputs equal zero, the metric is undefined; mark the route HOLD instead of reporting zero. No price amount or workload result is inferred here.

A fictional recovery trace

This example illustrates the ledger; it is not a live GPT Image 2.5 test.

Field	Example
Business job	HERO-184, one approved 4:3 concept
Application attempt	HERO-184-A2; application owns retry; SDK retries disabled and version pinned
Transport submission	S2, provider request ID retained
Failure signal	Transient rate-limit code/body with HTTP 429; not credit, spend or usage exhaustion
Recovery lane	Wait and retry after Retry-After, plus jitter
Budget	One retry remaining, 90-second deadline, fixed spend ceiling
Result	Final stream consumed, asset checksum recorded, creative review pending
Accounting	Both submissions plus Responses mainline and image usage retained

This accounting aligns failure recovery with the route decision. A model that is inexpensive per nominal image can still be the costly route if it creates many retries, unknown outcomes or rejected assets.

What this article did not test

No live GPT Image 2.5 request, rate limit, timeout, moderation block, partial stream, cost or latency was tested. Published limits and error details should be rechecked against the current official model, API and account documentation. Third-party provider behavior was not generalized to OpenAI.

The cover is an original conceptual illustration of a recovery router. It is not a real Genflow queue, provider dashboard, benchmark or generated result from GPT Image 2.5.

Make failure states reviewable

A resilient image pipeline is not one that retries everything. It is one that can explain why a request moved, stopped, changed or cost more than expected. Keep job and attempt IDs separate, branch on stable error evidence, cap retries by time and spend, reconcile uncertainty and send policy or quality decisions to the right owner.

You can apply the same recovery ledger around Genflow's currently available GPT Image 2 workflow. Recheck the active Studio model list and controls before translating upstream GPT Image 2.5 settings into a Genflow plan.