Handle errors and retries
Diagnose widget failures and recover without creating duplicate try-ons.
Reviewed by Closku documentation team ·
Choose a recovery action
- Correct the request: Missing fields or
invalid_idrequire valid UUIDs and the documented payload. Check the endpoint reference for the exact response. - Correct configuration: For
origin_not_allowed, compare the exact origin with the owner's saved domains. For inactive or missing configuration, check Your Widget. For a failed job withmissing_productormissing_garment_image, inspect the active product mapping and images. - Restore capacity: For
merchant_not_entitled_for_try_onortry_on_limit_reached, ask the owner to check billing and usage and limits. - Wait for a safe read: If a known job's status request temporarily fails, retry that status lookup with a bounded delay. A 429 means slow down. Stop and contact support if the issue persists.
Avoid duplicate submissions
A failed request, a 202 response already marked failed, and a job that fails later are different outcomes. Inspect a returned jobId and status. A 202 is not a promise of success. Status lookup may advance processing and persist the outcome; it is the supported completion operation, not a guarantee of no server effects.
Submission has no documented idempotency key. Do not automatically retry a POST after a timeout, lost response, or ambiguous server error. Even usage_check_unavailable does not prove no job was created. If you have a job ID, poll that job instead. Without one, there is no documented session-to-job lookup: contact support with the time, merchant ID, and non-sensitive error details. Do not send shopper photos or secret keys.
Failed jobs are intended to release their usage reservation; do not promise an immediate or unconditional refund. If the outcome or usage remains unclear, ask support before creating another attempt.
Completion and webhooks
Widget completion is retrieved by polling the known job ID with its merchant ID. Poll at a bounded interval and stop on completed or failed, cancellation, or a timeout. If polling stops while a job is still pending, retain the ID for a later status check rather than submit again. The current widget API does not document a merchant completion webhook.
Use the bounded polling example and Try-on status contract. Contact support if the known job remains unresolved.