Resolve and poll

POST resolve reference

POST /v2/images/resolve with X-API-Key, JSON selection and an optional stable Idempotency-Key. HTTP 202 means preparation is pending with no requested variant ready. HTTP 200 may be ready, partial or terminally failed. Always inspect data.variants, data.status and data.settled.

GET status reference

For pending work, wait for Retry-After and GET the exact relative Location or data.status_url on the same API origin, with the same workload authentication. The URL preserves size, format and recipe selection. GET returns 200 while processing; stop only when settled, on a terminal error, or at your application's deadline. Use retry_after_seconds plus bounded jitter between polls.

Polling does not create work. A 409 image_variants_not_requested means you must resolve that selection first. An API dependency outage is not evidence that previously accepted work failed; retain its status URL and retry within your deadline. Optional Images notifications are not required for this workflow.

For an uncertain POST response, repeat the same body and idempotency key. A 409 idempotency_replay provides error.detail.original_request_id and, when recoverable, error.detail.status_url. Follow the status link. Do not rotate keys on every retry: that creates separate operation identities.