Errors and limits

Error envelope

Every error response — regardless of status code — uses the same shape:

{"error": {"code": "not_found", "message": "Product not found"}}

code is a stable, machine-readable string safe to branch on in your integration. message is for humans (logs, debugging) — don’t parse it.

Error codes

Code	Status	Meaning
`unauthorized`	401	Missing or invalid API key
`not_found`	404	Resource doesn’t exist, or belongs to another shop
`validation_error`	400	Request body failed validation (missing required field, bad type, etc.)
`rate_limited`	429	Too many requests — see Rate limits below
`invalid_url`	400	Image `url` isn’t a well-formed URL
`unreachable_url`	400	Image URL couldn’t be fetched (timeout, DNS, non-2xx, not publicly reachable)
`not_an_image`	400	Image URL resolved but isn’t JPEG/PNG/WebP/GIF
`too_large`	400	Image exceeds 15 MB

The last four also appear per-URL in images_failed on POST /v1/products — see Images.

Rate limits

120 requests per minute per API key. Exceeding it returns 429 with a Retry-After header telling you how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{"error": {"code": "rate_limited", "message": "Rate limit exceeded"}}

Back off for at least Retry-After seconds before retrying. If you’re bulk-importing a catalog, space requests out rather than firing them all at once — see the pagination note below if you’re also listing large result sets.

Cross-shop access

Every request is scoped to the shop that owns the API key. Trying to GET, PATCH, or DELETE a product (or image) that belongs to a different shop returns 404 not_found — the same response as a genuinely nonexistent id. This is deliberate: it never confirms or denies that a resource exists for another shop.

Pagination

GET /v1/products is paginated with two query params:

Param	Default	Max
`page`	1	—
`limit`	20	100

curl "https://api.integration.tryonvirtual.com/v1/products?page=2&limit=50" \
  -H "Authorization: Bearer tryon_sk_your_key"

The response includes total, page, and limit alongside products, so you can compute whether there’s another page (page * limit < total) without a separate count call. You can combine pagination with category, tryon_status, and external_id filters — see the API reference for the full parameter list.

You now have everything needed to create products, manage images, and drive try-on end-to-end. From here:

Quickstart — the full happy path in one page
Storefront integration — embedding the try-on button and bootstrap script in your theme templates