How do you handle a moderation refusal from OpenAI's Images API in production?
answer
- it is a 4xx, not a 429
- backoff will not help here
- edits screen the upload as well
- refusal rate deserves its own metric
- auto and low are the filtering settings
basics
~20 sA blocked image request returns HTTP 400 with a moderation_blocked error, not a rate-limit or server error. It is not retryable: surface a clear refusal, invite the user to rephrase, log the attempt for abuse review, and never loop on backoff.
solid answer
~50 sWhen a gpt-image request trips OpenAI's safety system, the Images API answers with a 4xx error carrying a `moderation_blocked` code rather than an image. The critical operational point is classification: this is a permanent rejection of that input, so it must not enter your retry-with-backoff path the way a 429 or a 5xx does. Retrying identical bytes and text burns quota and produces the same refusal. Handle it as its own branch — return a user-facing message that says the request was declined and suggests rephrasing, record the prompt and user for abuse monitoring, and count refusals as a distinct metric from errors so a spike is visible. Two details matter for edits specifically: the uploaded image is screened as well as the prompt, so user uploads can cause refusals on innocuous prompts, and gpt-image exposes a `moderation` parameter with `auto` and `low` settings for adjusting the model's own filtering strictness.
go deeper
Know that a blocked request comes back as a client error with a moderation code and no image, and that retrying the same prompt will not help. Say you would show the user a clear message rather than an exception.
Distinguish this 4xx from rate limits and server errors in your retry policy, branch on the error code rather than the status alone, and note that image edits screen the uploaded file as well as the prompt.
Describe the production handling end to end: explicit error classification, fail-fast UX with useful copy, abuse logging, refusal rate as its own metric, and pre-screening prompts before spending a call. Be precise about what the moderation parameter does and does not relax.
Own the policy posture — where pre-screening sits, what is logged and retained for trust and safety, how refusal copy avoids becoming a boundary-probing oracle, whether relaxed filtering is justified for the domain, and how AI-provenance metadata is preserved through the asset pipeline.
## Refusal is a distinct failure class Every robust API client sorts failures into buckets: transient (retry), rate-limited (retry after a delay), and permanent (do not retry). Moderation refusals belong firmly in the third bucket, and the most common production bug is putting them in the first. A generic "retry any failure three times with exponential backoff" wrapper turns one refused generation into three refusals, triples the latency the user waits through, and consumes rate-limit allowance for nothing. The Images API signals this with a client error and a `moderation_blocked` error code, with a message explaining the request was rejected by the safety system. Your client should branch on the error code, not on the HTTP status alone, because a 400 can equally mean an invalid `size` value or a malformed mask — a developer bug, which needs a completely different response than a content refusal. ## Two moderated inputs, not one Generation screens the prompt. Editing screens the prompt **and the uploaded images**. That asymmetry catches teams that only tested generation. In a product where end users upload photographs, refusals will arrive on prompts that are entirely benign — for example, when an uploaded image contains identifiable real people or other content the safety system declines to transform. The user experience must reflect this: a message saying "your prompt was rejected" is confusing and wrong when the trigger was the upload. Word the refusal so it covers both possibilities, or use the error detail you have to distinguish. ## The moderation parameter gpt-image models accept a `moderation` parameter with values `auto` (the default) and `low`, which relaxes the model's own content filtering. It is a real lever for applications whose legitimate domain — medical illustration, security research, certain creative or editorial work — brushes against default caution. It is not a bypass: platform-level policy still applies, and using it does not exempt you from the usage policies. Treat it as a deliberate, documented product decision with its own risk review, not as the default you set to stop seeing errors. ## What to build 1. **Classify the error explicitly.** Separate branches for moderation refusal, invalid request, rate limit, and server error. Only the last two are retryable, and only the rate-limit branch should honour a retry delay. 2. **Fail fast to the user.** A refusal should reach the UI in one round trip with a plain message: the request was declined, here is what you can try. Do not spin a progress indicator through pointless retries. 3. **Log for abuse signals.** Persist user id, prompt, whether an upload was involved, and a timestamp. One refusal is noise; a user generating dozens is a pattern that belongs in your trust-and-safety process, and you need the data to see it. 4. **Meter refusals separately.** A refusal rate that jumps overnight usually means either a new abusive user cohort or a shift in filtering behaviour. Buried inside a general error rate, neither is visible. 5. **Screen before you spend.** For user-driven products, running your own moderation check on the prompt before calling the image endpoint saves latency and money on the obvious cases and gives you a first-party record of what you blocked. ## Provenance on the output side Safety is not only about refusals. Images returned by the gpt-image models carry C2PA provenance metadata identifying them as AI-generated. If your pipeline re-encodes, crops or strips EXIF on the way to storage, you may discard that metadata; whether that matters depends on your jurisdiction and your product's disclosure commitments, but it should be a conscious choice rather than an accident of an image-processing step. ## Designing the user-facing message Refusal copy is a real design problem. Too vague and users retry blindly; too specific and you hand a probe-by-error oracle to someone trying to find the boundary. The usual balance is a short, non-judgemental statement that the request could not be completed, plus a constructive suggestion to rephrase or use a different image — with no detail about which term or region triggered the block, and no implication that the user did something wrong when they may not have. ## What interviewers are checking They are probing whether you have run user-facing generative features. The signals of experience are: knowing the refusal is not retryable, knowing that edits moderate the uploaded image too, treating refusal rate as its own metric, and being careful and specific about the `moderation` parameter rather than describing it as a way to turn safety off.
- Why is retrying a moderation refusal with exponential backoff actively harmful?Because the outcome is deterministic for that input: identical prompt and image get refused again. The retries add seconds of latency to a user already waiting, consume rate-limit allowance that legitimate traffic needs, and mask the signal in your dashboards by inflating error counts. It also delays the only useful response, which is telling the user the request was declined so they can rephrase.
- A user reports the generator 'randomly fails' on some of their photos with a normal prompt. What is your first hypothesis?That the edits endpoint is refusing the uploaded image rather than the prompt — commonly images containing identifiable real people. Check whether the failing calls are edits with user-supplied images and whether the error code is the moderation one. The fix is usually product-side: screen uploads earlier and word the refusal so it names the image as a possible cause, not just the text.
- When is setting the moderation parameter to low the right call?When your application has a legitimate domain that default caution over-blocks — clinical, forensic, security or certain editorial imagery — and you have reviewed the usage policies and accepted the responsibility. It relaxes the model's own filtering, not platform policy, so refusals still happen. Make it an explicit, documented decision with its own logging, never a reflexive setting applied to stop error noise.
saying these in an interview costs you the question
- Retries the refusal with exponential backoff
- Treats it as a rate-limit or transient server error
- Assumes only the prompt is moderated, never the uploaded image
- Describes the moderation parameter as switching safety off
- Shows the user a raw provider error string with no guidance