Skip to main content
Image enhancement is asynchronous. An enhancement can complete fully, fail fully, or finish with a mix of completed and failed items.

​
Read item errors

Status responses include error_code and error_message for failed items. 
{
  "external_id": "sku_123",
  "status": "failed",
  "result_url": null,
  "thumbnail_url": null,
  "error_code": "invalid_source_url",
  "error_message": "Source URL target is not allowed."
}
Use external_id to show the failure beside the affected product in your internal tooling.

​
Retry decisions

FailureRetry?Recommended action
invalid_source_urlNoFix the URL or CDN configuration.
unsupported_file_typeNoConvert the image to JPEG, PNG, or WebP.
file_too_largeNoResize or compress the source image below 10 MB.
content_policy_violationNoRemove unsupported content from the request.
download_timeoutMaybeRetry after improving source hosting reliability.
provider_errorYesRetry later with a new batch if the item remains failed.
storage_errorYesRetry later or contact support with request_id.
rate_limit_exceededYesWait for Retry-After.

​
Retrying failed items

When retrying failed items, create a new batch with a new Idempotency-Key. Do this only after you have fixed the input or confirmed the error is retryable. Do not reuse the old idempotency key with a modified body. That returns 409 idempotency_conflict.

​
User-facing product state

For marketplace or catalog tooling, treat each item independently. One failed image should not block successful images from being attached to their products. Recommended states in your product: 
Pending enhancement
Enhancement completed
Needs review
Retry queued
This gives operators a clear way to approve results, replace source photos, or retry only the failed items.