🎨 GPT Image

Match error codes and messages to troubleshoot GPT Image generation, editing, and delivery.

Common Top 10

Based on service data, ranked by share of GPT Image failure records. Equivalent balance and unsupported-model errors are combined. These percentages are not the image generation failure rate. Quotes show common user-visible messages; the same code can have other messages.

Insufficient balance

INSUFFICIENT_BALANCE / billing_error / upstream_error · HTTP 403

Example:

Insufficient account balance

insufficient balance

Solution:

Top up your account before submitting again. The code upstream_error alone does not establish a balance problem; check the message too.

Low balance? Top up

Missing key

missing_bearer_token · HTTP 401

Example:

Missing bearer token

Solution:

Add Authorization: Bearer YOUR_API_KEY. Check that your tool actually sends the authentication header to the image endpoint.

Need a key? Create oneChoose the 🎨 GPT Image group when creating your key.

Request rejected

400 · type: invalid_request_error · HTTP 400

Example:

您的请求无法用于生成图像。该请求可能因安全政策被拦截，或不适合进行图像生成。

Solution:

This message says the request may have been blocked by a safety policy or may not be suitable for image generation. Check the parameters, then revise the prompt and references when the message identifies a safety restriction. See 400 errors and moderation.

Wrong endpoint or request method

unsupported_images_endpoint · HTTP 404

Example:

Unsupported images endpoint: /v1/images/edits

Solution:

Check the Base URL, path, and method against the OpenAI Images examples. Use POST /v1/images/generations or POST /v1/images/edits, without adding /v1 twice.

Invalid key

invalid_api_key · HTTP 401

Example:

Invalid API key

Solution:

Check for missing characters, extra spaces, or an expired key. Use a valid key from a 🎨 GPT Image group.

Need a key? Create oneChoose the 🎨 GPT Image group when creating your key.

Model unavailable in this group

model_not_found / upstream_error · type: model_not_found · HTTP 404

Example:

Model "gpt-image-2" is not supported by any configured account in this group

Solution:

Copy the exact name from Model comparison and use a key for a group supporting it. Add openai/ for Studio; omit that prefix for OpenAI Images.

Generation connection failed

upstream_transport_error · HTTP 502

Example:

Upstream image request failed

Invalid parameter format

invalid_value · HTTP 400

Example:

size must be auto, 1K, 2K, 4K, or WIDTHxHEIGHT

Solution:

Correct the field named by param. For this size message, use auto, 1K, 2K, 4K, or a value such as 1024x1024, not 1024*1024.

Image service temporarily unavailable

upstream_error · HTTP 502

Example:

Upstream service temporarily unavailable

Solution:

Try again later. For an accepted Studio job, check its final state first. Widespread incidents and recovery updates are announced in the .

No capacity available in this group

upstream_error · type: api_error · HTTP 503

Example:

No available compatible accounts

Solution:

Try again later, or switch to another available image group using a key for that group.

Reference: static errors

These errors come from the service's request validation, job handling, or image processing. Studio and OpenAI Images can return a string error.code; an accepted Studio job reports its error in the job snapshot. Read message, param, and the HTTP status together.

Authentication and requests

Code	Common message	Resolution
`missing_bearer_token`	Missing bearer token	Send a complete Bearer authentication header.
`invalid_api_key` / `invalid_bearer_token`	Invalid API key / Invalid bearer token	Check or replace the key.
`missing_credential`	API key is required	Supply a key with the request.
`identity_resolution_failed`	Unable to resolve image request identity and concurrency
`invalid_model`	model must use openai/<model> or google/<model>	Prefix GPT Image model names with `openai/` in Studio.
`invalid_content_type`	Studio image submissions require application/json	Submit JSON with `Content-Type: application/json`.
`invalid_json`	Request body is not valid JSON / Request body must be an object	Send a valid JSON object; check quotes, commas, and the body.
`invalid_multipart`	Multipart body is invalid	Let your HTTP client construct the multipart body and boundary.
`invalid_request`	Only one mask is supported / Request JSON body must be an object / Invalid image Data URL	Check the mask count, JSON object, and image encoding as instructed by the message.
`invalid_value`	prompt must be a non-empty string / size must be auto, 1K, 2K, 4K, or WIDTHxHEIGHT	Correct the named field. GPT Image in Studio uses `size`, without `resolution` or `aspect_ratio`.
`request_too_large`	Request body is too large	Reduce the body below 512 MiB. Individual images have separate limits.
`unsupported_images_endpoint`	Unsupported images endpoint: …	Check the Images path and request method.
`unsupported_action` / `unsupported_protocol`	Unsupported OpenAI Images action: … / Unsupported OpenAI protocol route	Use the documented Images endpoints.
`method_not_allowed`	Method Not Allowed	Use POST for generation and editing, GET for documented reads.
`not_found`	Resource not found / Job not found / Media was not found	Check the path; use the original key and exact `jobId` for job requests.

Reference images and masks

Code	Common message	Resolution
`edit_image_required`	At least one image is required for edits	Include a reference image.
`edit_too_many_images`	Image edits support at most 16 input images	Use no more than 16 reference images.
`edit_too_many_masks`	Image edits support at most one mask	Include only one mask.
`edit_unsupported_image_type`	image is not a supported image	Use a valid PNG, JPEG, or WebP image.
`edit_unsupported_mask_type`	mask is not a supported image	Use a PNG mask with transparent areas.
`edit_image_too_large`	image exceeds maximum allowed size	Keep each OpenAI edit image within 50 MiB.
`edit_mask_too_large`	mask exceeds maximum allowed size	Keep the mask within 4 MiB.
`edit_mask_dimensions_mismatch`	mask dimensions must match the first input image	Match the first reference image's width and height exactly.
`invalid_image`	image is empty / image input could not be resolved	Check that the file opens and its URL returns an image, not a web page.
`invalid_value`	image Data URL is invalid	Check Base64 encoding and include the full `data:image/png;base64,...` prefix for a Data URL.
`image_too_large`	image exceeds maximum allowed size	Reduce the image. The shared input limit is 80 MiB; OpenAI edits have tighter limits.
`invalid_image_url`	image URL is not allowed	Use a publicly downloadable HTTPS image, without local addresses or required login.
`image_download_failed`	image URL could not be downloaded	Check access and expiry, or use an uploaded file or Data URL.
`unsupported_file_id`	images[0].file_id is not supported / mask.file_id is not supported	Use an image file, public URL, or Data URL.

Idempotency, jobs, and results

Code	Common message	Resolution
`invalid_idempotency_key`	Idempotency-Key must be 1-255 visible ASCII bytes	Use 1 to 255 visible ASCII characters, such as a UUID.
`idempotency_key_conflict`	Idempotency-Key is already bound to a different request	Keep the same request for recovery; use a new value for a new task.
`idempotency_not_supported_for_streaming`	Idempotency-Key is not supported for streaming requests	Omit the key for native streaming, or use non-streaming or Studio for idempotent recovery.
`job_not_finished`	Job is not finished	Wait for `completed` before requesting the result.
`cancelled`	Job was cancelled / Image generation was cancelled	Stop polling; explicitly submit a new task if still needed.
`result_expired`	Result has expired / Media has expired	The original result is no longer retrievable. Download future results before expiry.
`media_unavailable`	Result media is unavailable / Media is unavailable
`submission_failed`	Failed to submit image request	The submission outcome may be unknown. Recover with the same key, idempotency value, and request if you used one.
`generation_interrupted`	Image generation was interrupted
`generation_error`	Image generation failed
`internal_error`	Internal server error

Images and results are retained for 72 hours. A retrieval failure does not necessarily mean generation failed; see Billing and recovery.

Generation connections and image delivery

Code	Common message
`upstream_transport_error`	Upstream image request failed
`upstream_error`	Upstream image generation failed
`upstream_invalid_response`	Upstream OpenAI Images response is not valid JSON / Upstream stream image payload is invalid
`upstream_response_too_large`	Upstream response is too large
`invalid_upstream_image`	upstream image base64 is invalid / upstream image could not be located
`upstream_image_too_large`	upstream image exceeds maximum allowed size
`upstream_image_download_failed`	upstream image could not be downloaded
`media_delivery_failed`	upstream image could not be stored

Reference: dynamic errors

These codes, types, and message excerpts have been returned to users. Only wrapped public information is included, without raw upstream responses. An upstream_error can concern balance, models, limits, or availability; check type and message as well.

Code or type	User-visible message or excerpt	Resolution when the cause is explicit
`INSUFFICIENT_BALANCE` / `billing_error`	Insufficient account balance / insufficient balance	Low balance? Top up
`API_KEY_QUOTA_EXHAUSTED`	API key 额度已用完	Check the key's spending cap; it may be exhausted even when the account has funds.
`400` / `invalid_request_error`	您的请求无法用于生成图像。该请求可能因安全政策被拦截，或不适合进行图像生成。	Revise the prompt and references, and check parameters.
`429`	No available image quota. Please try again later.	Wait for capacity; this message is not the same as insufficient account balance.
`ContentModerationRejected`	提示词或参考图未通过内容审核，请修改后重试	Revise the prompt or references before submitting again.
`moderation_blocked`	Your request was rejected by the safety system.	Revise the content and follow content policies.
`content_moderation`	Request rejected by upstream validation. Please check your prompt, parameters and input media, then try again.	Check the prompt, parameters, and reference images.
`ERR-*` · `content_policy_error` / `invalid_request_error`	A public reference code starting with `ERR-`; the accompanying message varies	Follow the public message. Revise content when it identifies a policy issue.
`API_PARAM_VALIDATION_FAILED` / `invalid_value`	Invalid size '3072x4096'. The longest edge must be less than or equal to 3840.	Reduce the longest edge as instructed by this model's response.
`invalid_value` · `image_generation_user_error`	Parameter or image input does not meet the current model's requirements	Correct the field identified in the response.
`InvalidInput`	提示词或嵌入内容无效或过长，请仅保留本次生成指令并移除历史对话后重试。	Shorten the prompt and remove unrelated conversation history.
`InvalidRequest`	At least one uploaded image is required	Include a reference file and check the multipart body actually sent.
`GenerationRequestFailed`	生成请求失败，请检查参数后重试	Check the documented parameters and request format.
`invalid_request_error`	images endpoint requires an image model, got "gpt-image"	Use a complete model name from the model guide.
`service_error`	/v1/images/edits requires multipart/form-data	Use the multipart example when uploading image files.
`model_disabled`	The model 'gpt-image-2.5-flare' is currently disabled. Please use another available model.	Select an available model.
`model_not_found`	Model "gpt-image-2" is not supported by any configured account in this group	Check the model name and key group.
`model_temporarily_unavailable`	The model is temporarily unavailable.	Try later or select another available model.
`not_found_error`	Images API is not supported for this platform	Use a group supporting Images and the matching protocol.
`permission_error`	Image generation is not enabled for this group	Use a key from an image-enabled group.
`rate_limit_error`	Upstream rate limit exceeded, please retry later	Wait before submitting again; reduce concurrency when the message identifies that limit.
`api_error`	No available compatible accounts	Try later or switch to an available group.
`upstream_error`	Insufficient account balance / Upstream service temporarily unavailable / No available compatible accounts	Match the complete public message to balance, availability, or capacity guidance.

generation_interrupted, invalid_upstream_image, upstream_image_download_failed, and upstream_transport_error also occur in failure records; their fixed public meanings appear in the static index above. ERR-* denotes a family of reference codes, not a literal code to submit.

Common Top 10

Reference: static errors

Authentication and requests

Reference images and masks

Idempotency, jobs, and results

Generation connections and image delivery

Reference: dynamic errors

On this page