Widget errors and reliability
Diagnose failures using the HTTP response, JSON error, merchant configuration, and job status. Retry reads carefully and avoid duplicate submissions.
Reviewed by Closku documentation team ·
HTTP errors
| Status | Current widget behavior | Next action |
|---|---|---|
| 400 | Required request field missing | Check camelCase fields in the API reference |
| 402 | merchant_not_entitled_for_try_on | Review merchant subscription and account access |
| 403 | origin_not_allowed, widget_inactive, or configuration lookup failure | Confirm origin and active configuration |
| 404 | Configuration unavailable, merchant inactive, or job lookup unavailable | Check IDs and preserve the exact error |
| 500 | Processing, session-validation, or downstream service failure | Inspect the JSON error; correct an invalid session or retry a transient read with bounded backoff |
Job failures and HTTP success
A submission can return HTTP 202 with a job already marked failed. Poll it to read the error. Preparation errors include missing_product, missing_garment_image, shopper_image_invalid, and shopper_upload_failed; inference can also fail or be unavailable.
For shopper_image_invalid, submit a supported base64 image data URL from the selected file; HTTP(S) shopper-photo URLs are rejected. An expired, missing, or cross-merchant session is rejected before job creation and currently returns HTTP 500 with a session error. Correct session_not_found, session_expired, or session_merchant_mismatch instead of treating them as transient server errors.
Check product mapping and the garment image before asking the shopper to upload again. The estimated processing field is not a deadline or accuracy guarantee.
Retry without duplicate jobs
Retry transient configuration, product-list, or status reads with bounded backoff. Stop on completed or failed, avoid overlapping polling loops, and stop when the shopper closes the widget.
Try-on submission does not implement Idempotency-Key. After an ambiguous POST timeout, inspect any returned job ID first. A repeated submission can create another job and record additional activity; let the user choose a retry when the original outcome is unknown.
A 402 or 403 needs an account or configuration correction. Production origin validation rejects an empty allowlist as well as a mismatched storefront. No widget 429 or Retry-After contract should be assumed.
Support and evidence
Send the merchant ID, storefront origin, affected product ID, job ID if available, response code and error, timestamp with timezone, and checks already performed. Keep shopper photos, account cookies, and secrets out of ordinary logs and support messages. Service commitments and Enterprise SLAs follow the actual agreement; no unverified uptime, backup, or response-time guarantee is published here.
Next steps
Check exact fields and routes.
Recheck the first working flow.
Related pages
Separate job states from transport errors.
Use operational first checks.