# Errors

> Every error code the TryYourSize API returns, with its HTTP status and what to do. Each error's doc_url links here.

Source: https://docs.tryyoursize.com/api/errors/

Every error has the same shape:

```json
{
  "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](https://docs.tryyoursize.com/quickstarts/web.md#errors).

## Codes

| Code | Status | Retry? |
|---|---|---|
| [`invalid_request`](#invalid_request) | 400 | No, fix the request |
| [`unauthorized`](#unauthorized) | 401 | No |
| [`reauth_required`](#reauth_required) | 401 | After signing in again |
| [`payment_required`](#payment_required) | 402 | No |
| [`forbidden`](#forbidden) | 403 | No |
| [`not_found`](#not_found) | 404 | No |
| [`conflict`](#conflict) | 409 | No |
| [`unprocessable`](#unprocessable) | 422 | No, fix the values |
| [`rate_limited`](#rate_limited) | 429 | Yes, after `Retry-After` |
| [`internal_error`](#internal_error) | 500 | Yes, with backoff |
| [`not_implemented`](#not_implemented) | 501 | No |
| [`unavailable`](#unavailable) | 503 | Yes, with backoff |
| [`invalid_api_version`](#invalid_api_version) | 400 | No |
| [`idempotency_key_in_use`](#idempotency_key_in_use) | 409 | Yes, same key |
| [`idempotency_key_reused`](#idempotency_key_reused) | 422 | No, new key |
| [`invalid_idempotency_key`](#invalid_idempotency_key) | 400 | No |
| [`handle_expired`](#handle_expired) | 401 | With a new handle |
| [`handle_invalid`](#handle_invalid) | 401 | No |
| [`handle_mode_mismatch`](#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](https://docs.tryyoursize.com/get-started/keys-and-modes.md#key-scopes), 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](https://docs.tryyoursize.com/guides/rate-limits.md).

## 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](mailto:support@tryyoursize.com) 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](https://docs.tryyoursize.com/api/changelog.md), for example `2026-10-25`, or omit the header to get the latest. See [Versioning](https://docs.tryyoursize.com/guides/versioning.md).

## 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](https://docs.tryyoursize.com/guides/idempotency.md).

## 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](https://docs.tryyoursize.com/guides/server-side-recommendations.md).

## 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.