Errors

Every error has the same shape:

{
  "error": "product not found",
  "status": 404,
  "code": "not_found",
  "doc_url": "https://docs.tryyoursize.com/api/errors/#not_found",
  "request_id": "0d6c1c5e-…"
}

Field
error	A human-readable message. It can change: do not match on it.
status	The HTTP status.
code	Stable and machine-readable. Branch on this.
doc_url	A link to the code’s section on this page.
request_id	Identifies the request, also in the X-Request-ID response header. Quote it when you contact support. You can send your own X-Request-ID to correlate with your logs.

The SDKs raise TryYourSizeError (Node: code, docUrl, requestId) and tryyoursize.APIError (Python: code, doc_url, request_id). Browser and mobile SDK errors have their own codes, listed in each quickstart.

Codes

Code	Status	Retry?
invalid_request	400	No, fix the request
unauthorized	401	No
reauth_required	401	After signing in again
payment_required	402	No
forbidden	403	No
not_found	404	No
conflict	409	No
unprocessable	422	No, fix the values
rate_limited	429	Yes, after Retry-After
internal_error	500	Yes, with backoff
not_implemented	501	No
unavailable	503	Yes, with backoff
invalid_api_version	400	No
idempotency_key_in_use	409	Yes, same key
idempotency_key_reused	422	No, new key
invalid_idempotency_key	400	No
handle_expired	401	With a new handle
handle_invalid	401	No
handle_mode_mismatch	403	No

invalid_request

400. The request is malformed: invalid JSON, a missing or wrong-typed field, an unknown field (for example a customer email in an order), or a parameter out of range (limit above 100, more than 25 products). The message names the field. Fix the request; do not retry it unchanged.

unauthorized

401. No key, an unknown key, a revoked or expired key (a rolled key after its overlap), a key of a disabled store, or a publishable key used where a secret key is needed. Check the Authorization: Bearer sk_… header and the key’s status in Studio → Developers → API keys.

reauth_required

401. A Studio action that needs a recent sign-in (for example creating, rolling or revoking a live secret key). Sign in again in Studio and repeat the action. Server API calls with keys never get this code.

payment_required

402. Your plan does not include this: for example publishing more styles than the plan allows, or another store on Starter. Upgrade in Studio → Settings → Billing, or retire a style.

forbidden

403. The key is valid but not allowed to do this: a restricted key without the operation’s key scope, or a publishable key used from an origin that is not registered for it.

not_found

404. The object does not exist for this key’s store (a product ID or SKU, a garment, a fit group), or a return refers to an order you have not sent yet. Objects of other stores are always “not found”.

conflict

409. The request conflicts with the current state: a SKU that already exists in the store, a second draft for a product, or a change to a published garment version (published versions never change).

unprocessable

422. The values are well-formed but cannot be accepted. For garments, the answer lists each issue with the field, size and point of measure to fix (for example an impossible measurement, a missing required point of measure, or a shop size with no Studio size in the size map when publishing).

rate_limited

429. Too many requests. Wait for the number of seconds in Retry-After, then retry with backoff. See Rate limits.

internal_error

500. Something failed on our side. Retry with exponential backoff (with the same Idempotency-Key for a POST). If it persists, contact support with the request_id.

not_implemented

501. The endpoint exists in the specification but is not available yet. It is listed as coming soon in these docs.

unavailable

503. A dependency is temporarily unavailable, or a feature is switched off for your store (for example the Shopify order import before it is enabled). Retry later with backoff.

invalid_api_version

400. The TYS-Version header is not a known version. Send a date from the changelog, for example 2026-10-25, or omit the header to get the latest. See Versioning.

idempotency_key_in_use

409. A request with the same Idempotency-Key is still being processed. Wait a moment and retry with the same key: you will get the first request’s response. See Idempotency.

idempotency_key_reused

422. This Idempotency-Key was already used in the last 24 hours with a different request body. Use a new key for a new request.

invalid_idempotency_key

400. The Idempotency-Key is empty, longer than 255 characters or not printable ASCII. A UUID v4 is ideal.

handle_expired

401. The recommendation handle is older than one hour. Ask the browser for a new one with tys.recommendationHandle(). See Server-side recommendations.

handle_invalid

401. The recommendation handle cannot be used: it is malformed or was tampered with, it was issued for another store, or the shopper has since deleted their TryYourSize account or disconnected your store. Do not retry; treat the shopper as not connected.

handle_mode_mismatch

403. The handle was issued in test mode and the key is live (or the reverse). Use a key of the same mode as the publishable key on the page.