Handle every gpt-image-2 API error gracefully — auth, validation, credit balance, rate limits, retries. Stable error codes your client can branch on safely.

Errors

All error responses follow a uniform envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "request_id": "req_abcdef1234567890"
  }
}

Every response — error or success — also sets the X-Request-Id header to the same value.

Field	Description
`code`	Stable, machine-readable error code. Safe to branch on.
`message`	Human-readable explanation. May change between versions.
`request_id`	Correlation ID for support — include it when reporting issues.

Error codes

Code	HTTP	Retryable	Meaning
`UNAUTHORIZED`	401	No	Missing, malformed, or invalid `Authorization` header; key disabled, expired, or leaked through a query string. All variants return the same response — no information is revealed about which case applies.
`INVALID_REQUEST`	400	No	Body failed validation (empty prompt, unsupported aspect ratio, `n` out of range, invalid reference URL), or the request body was not valid JSON. Fix the request and retry.
`INSUFFICIENT_CREDITS`	402	No (until top-up)	Your credit balance is below `2 × n`. The response body includes `required` and `available` fields for context. Top up from the Credits page, then retry.
`NOT_FOUND`	404	No	The task ID does not exist, belongs to another user, or was created through the web Studio (API tasks only).
`RATE_LIMITED`	429	Yes	Per-key rate limit hit. Back off and retry. The response includes a `Retry-After` header (seconds).
`INTERNAL_ERROR`	500	Yes	Unexpected server-side error. Include the `request_id` when contacting support.

Retry guidance

Scenario	Safe to retry	Recommended action
Network error (no response) on `POST /generate`	No*	The task may have been created and charged even though you didn't get a response. Before retrying, call `GET /api/v1/images/task` to check your recent tasks.
`401 UNAUTHORIZED`	No	Check the key, rotate if compromised
`400 INVALID_REQUEST`	No	Fix the request body first
`402 INSUFFICIENT_CREDITS`	No	Top up first
`429 RATE_LIMITED`	Yes	Respect `Retry-After`; exponential backoff otherwise (1s, 2s, 4s, …, max 60s)
`500 INTERNAL_ERROR`	Yes	Exponential backoff: 2s, 4s, 8s, max 3 attempts
`404 NOT_FOUND` on a task you just created	Maybe	Rare race between creation commit and first poll. Retry once after 1s.

The API does not implement an Idempotency-Key header. Blindly retrying a POST /api/v1/images/generate after a network timeout can create duplicate tasks and duplicate charges. If you don't know whether your previous request reached the server, call GET /api/v1/images/task first to list your recent tasks.

Task-level failures vs. API-level errors

Two distinct kinds of "failures":

API-level errors — the HTTP request itself returns a 4xx / 5xx with an error block. The task was never created, or was rejected before reaching the generator. Credits are never charged for these.
Task-level failures — POST /api/v1/images/generate returned 200 successfully, but polling the task later returns status: "failed" with an error message. Credits are automatically refunded by the background worker.

Handle both cases in your client code.

Debugging tips

Include `request_id` in support tickets

Every error response carries a request_id, and every response also sets the X-Request-Id response header. Send this ID when contacting support so we can correlate server logs.

Common `INVALID_REQUEST` causes

prompt empty or not a string
aspect_ratio is not one of the 13 supported values
n not an integer in [1, 4]
reference_images contains more than 4 entries
A reference_images entry is not an http:// or https:// URL (base64 / data URIs are rejected)
Request body is not valid JSON

Why does a well-formed `Authorization` header still return 401?

The server folds several causes into the same UNAUTHORIZED response, deliberately, to avoid leaking information:

API key typed incorrectly or revoked
API key passed over HTTP in production (HTTPS is required)
API key leaked via a query string (?api_key=..., ?token=..., etc.) — the server always rejects such requests and you should rotate the key immediately

Content policy rejections

If a prompt or reference image violates content policy, the task will typically be accepted at submission time and then fail during generation. You'll see status: "failed" on polling, and credits will be refunded. Repeated violations may result in key suspension.

Errors

All error responses follow a uniform envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "request_id": "req_abcdef1234567890"
  }
}

Every response — error or success — also sets the X-Request-Id header to the same value.

Field	Description
`code`	Stable, machine-readable error code. Safe to branch on.
`message`	Human-readable explanation. May change between versions.
`request_id`	Correlation ID for support — include it when reporting issues.

Error codes

Code	HTTP	Retryable	Meaning
`UNAUTHORIZED`	401	No	Missing, malformed, or invalid `Authorization` header; key disabled, expired, or leaked through a query string. All variants return the same response — no information is revealed about which case applies.
`INVALID_REQUEST`	400	No	Body failed validation (empty prompt, unsupported aspect ratio, `n` out of range, invalid reference URL), or the request body was not valid JSON. Fix the request and retry.
`INSUFFICIENT_CREDITS`	402	No (until top-up)	Your credit balance is below `2 × n`. The response body includes `required` and `available` fields for context. Top up from the Credits page, then retry.
`NOT_FOUND`	404	No	The task ID does not exist, belongs to another user, or was created through the web Studio (API tasks only).
`RATE_LIMITED`	429	Yes	Per-key rate limit hit. Back off and retry. The response includes a `Retry-After` header (seconds).
`INTERNAL_ERROR`	500	Yes	Unexpected server-side error. Include the `request_id` when contacting support.

Retry guidance

Scenario	Safe to retry	Recommended action
Network error (no response) on `POST /generate`	No*	The task may have been created and charged even though you didn't get a response. Before retrying, call `GET /api/v1/images/task` to check your recent tasks.
`401 UNAUTHORIZED`	No	Check the key, rotate if compromised
`400 INVALID_REQUEST`	No	Fix the request body first
`402 INSUFFICIENT_CREDITS`	No	Top up first
`429 RATE_LIMITED`	Yes	Respect `Retry-After`; exponential backoff otherwise (1s, 2s, 4s, …, max 60s)
`500 INTERNAL_ERROR`	Yes	Exponential backoff: 2s, 4s, 8s, max 3 attempts
`404 NOT_FOUND` on a task you just created	Maybe	Rare race between creation commit and first poll. Retry once after 1s.

Task-level failures vs. API-level errors

Two distinct kinds of "failures":

API-level errors — the HTTP request itself returns a 4xx / 5xx with an error block. The task was never created, or was rejected before reaching the generator. Credits are never charged for these.
Task-level failures — POST /api/v1/images/generate returned 200 successfully, but polling the task later returns status: "failed" with an error message. Credits are automatically refunded by the background worker.

Handle both cases in your client code.

prompt empty or not a string
aspect_ratio is not one of the 13 supported values
n not an integer in [1, 4]
reference_images contains more than 4 entries
A reference_images entry is not an http:// or https:// URL (base64 / data URIs are rejected)
Request body is not valid JSON

Why does a well-formed `Authorization` header still return 401?

The server folds several causes into the same UNAUTHORIZED response, deliberately, to avoid leaking information:

API key typed incorrectly or revoked
API key passed over HTTP in production (HTTPS is required)
API key leaked via a query string (?api_key=..., ?token=..., etc.) — the server always rejects such requests and you should rotate the key immediately

Errors

Errors

Error codes

Retry guidance

Task-level failures vs. API-level errors

Debugging tips

Include `request_id` in support tickets

Common `INVALID_REQUEST` causes

Why does a well-formed `Authorization` header still return 401?

Content policy rejections

Inhaltsverzeichnis

Errors

Errors

Error codes

Retry guidance

Task-level failures vs. API-level errors

Debugging tips

Include `request_id` in support tickets

Common `INVALID_REQUEST` causes

Why does a well-formed `Authorization` header still return 401?

Content policy rejections

Inhaltsverzeichnis