Skip to main content
API errors use a consistent JSON shape. 
{
  "error": {
    "code": "invalid_payload",
    "message": "The request payload is invalid.",
    "request_id": "req_..."
  }
}
Use request_id when contacting support or correlating API responses with logs and webhook events.

​
Authentication and account errors

HTTP statusCodeRecommended handling
401missing_api_keySend Authorization: Bearer <api_key>.
401invalid_api_keyCheck the key value and header format.
401api_key_expiredRotate to a non-expired key.
401api_key_inactiveReactivate or rotate the key.
401api_key_revokedRotate to a new key.
403api_key_environment_mismatchUse a key from the correct environment.
403email_not_verifiedVerify the account email before using the API.
403account_suspendedContact support.
403api_access_not_enabledEnsure the account meets live API credit requirements.
403payment_risk_restrictedResolve the account billing or risk restriction.

​
Request validation errors

HTTP statusCodeRecommended handling
400invalid_payloadFix the JSON body before retrying.
400invalid_idempotency_keySend a valid Idempotency-Key header.
400invalid_webhook_urlUse a public HTTPS webhook URL.
422content_policy_violationRemove unsupported content from the request.

​
Source image item errors

Source image validation happens during item processing. These codes appear as item error_code values in enhancement status responses and webhooks, not as the create response for a valid enhancement request.
CodeRecommended handling
invalid_source_urlUse a public HTTP or HTTPS image URL that passes target validation.
source_url_dns_failedFix the source image hostname or DNS configuration.
source_url_redirect_limitReduce redirects to 3 or fewer.
source_url_unreachableMake the image URL reachable by the server.
download_timeoutImprove source hosting reliability or retry later.
file_too_largeUse an image under 10 MB.
unsupported_file_typeUse JPEG, PNG, or WebP with a correct MIME type.

​
Enhancement and credit errors

HTTP statusCodeRecommended handling
402insufficient_api_creditsAdd paid API-eligible credits or reduce batch size.
409idempotency_conflictUse the same body for the same key, or create a new key for a new batch.
429too_many_active_enhancementsWait for an active batch to finish.
429rate_limit_exceededWait for Retry-After before retrying.
404enhancement_not_foundCheck the enhancement id and key environment.
400invalid_enhancement_idSend a valid UUID enhancement id.

​
System errors

HTTP statusCodeRecommended handling
500rate_limit_unavailableRetry later.
503queue_unavailableRetry later; reserved credits are refunded when queueing fails.
500unexpectedRetry later or contact support with request_id.
Item-level failures may also include provider or storage errors in status responses and webhooks.

​
Retry guidance

SituationRetry?How
Network timeout while creating an enhancementYesRetry with the same Idempotency-Key and exact same body.
429 rate_limit_exceededYesWait for Retry-After.
too_many_active_enhancementsYesWait until an active enhancement reaches a terminal status.
Provider or storage failure on an itemYesRetry later with a new batch and new idempotency key.
invalid_payload, invalid_source_url, unsupported_file_typeNoFix the input first.
insufficient_api_creditsNoAdd paid credits or reduce batch size first.