Errors

Two kinds of failure — don't conflate them

Request-level failures (the submit/query call itself errors): a non-2xx HTTP status plus an OpenAI-style error envelope.
Task-level failures (no image was produced): GET /v1/tasks/{task_id} still returns HTTP 200, but with data.status = failed and details in data.error (see Query tasks).

Request-level error envelope:

{ "error": { "message": "...", "type": "...", "code": "..." } }

HTTP	Meaning	What to do
`400`	Invalid parameters (count, aspect ratio, more than 15 reference images, etc.)	Check the request body
`401`	Missing / invalid API key (including a deleted or expired key)	Check `Authorization`; if a key was deleted or leaked, create a new one in the console
`402`	Insufficient credits	Top up
`403`	No access to the resource (e.g. querying someone else's task)	Only query your own tasks
`404`	Task does not exist or has expired	Verify the `task_id`; tasks have a retention window
`429`	Rate limited	Back off and retry
`5xx`	Gateway / upstream error	Retry later; contact support if it persists

A deleted key still works for a few seconds: deleting invalidates the cache and is effective immediately in almost all cases; under extreme concurrency there can be a very brief cache window. To be certain, confirm the key returns 401 after deletion.
Are failed tasks refunded?: for cases like timeouts the platform issues a refund; refunded tasks do not trigger a webhook callback — confirm them by polling.
Result image won't open: result image URLs expire 24 hours after completion — re-host them to your own storage before they expire.