API reference
Errors
Tool endpoints return { "success": false, "errorCode": "..." } with an HTTP status; the download endpoint returns { "error": "..." }. Handle these:
Error codes
| Parameter | Values | Notes |
|---|---|---|
| 401 unauthorized | No authenticated identity. Requests need a valid Bearer key (the website itself authorizes through the logged-in session). | |
| 402 insufficient_credits | Balance too low for the run — top up and retry. Nothing was debited. | |
| 403 account_banned | The account is banned. | |
| 404 not_found | Unknown task id on polling; the download endpoint returns 404 with an error field when no result exists. | |
| 413 image_too_large | Uploaded file over the tool file limit, or an imageUrl over the 60 MB fetch cap. | |
| 429 concurrency_limit | The account is at its running-task limit. | |
| 500 | Task could not be started or the download failed internally (error field). | |
| 502 image_fetch_failed | imageUrl could not be fetched in time or is not an image. |
Validation errors (400)
Parameter problems return 400 with a specific errorCode:
| Parameter | Values | Notes |
|---|---|---|
| image_required | No image or imageUrl on the request. | |
| image_unreadable | The image could not be decoded. | |
| image_too_large | Decoded image over an endpoint pixel cap (400 on Upscale/Seamless edge check; 413 on Home textiles). | |
| size_out_of_range | widthCm/heightCm outside 10–240. | |
| too_far | Source resolution too low to reach the target print size. | |
| invalid_params | Unknown enum value or missing required field. | |
| invalid_preset | Unknown Upscale/Seamless mode or resolution. | |
| invalid_mask | Unknown oval maskId. | |
| scene_required | Scene swap in scene mode without envId or sceneDesc. | |
| replace_desc_required | Scene swap in object mode without replaceDesc. | |
| drape_distance_required | Mockup drape=custom without drapeDistanceCm. |