Idempotency and retries

Networks fail. To retry a POST without doing it twice, send an Idempotency-Key header with a unique value per logical request (a UUID v4 is ideal; 1–255 printable ASCII characters).

curl https://api.tryyoursize.com/v1/products \
  -H "Authorization: Bearer $TYS_SECRET_KEY" \
  -H "TYS-Version: 2026-10-25" \
  -H "Idempotency-Key: 6f1c1f0e-7a8b-4c1e-9d6f-0b3a2e5c4d11" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"CREW-TSHIRT","name":"Crew T-shirt","category":"tshirt"}'

The SDKs take it as an option: { idempotencyKey } (Node) or idempotency_key= (Python).

How it behaves

Situation	Answer
First request	Runs normally. The response is stored for 24 hours, per store and mode (secret and restricted keys).
Retry with the same key and the same body	The stored response, with the header Idempotent-Replayed: true.
Retry while the first request is still running	409 idempotency_key_in_use: wait and retry.
Same key, different body	422 idempotency_key_reused: use a new key for a new request.
Malformed key	400 invalid_idempotency_key.
The first response was a 5xx	Not stored: a retry runs again.

Naturally idempotent endpoints

POST /v1/orders is idempotent by your order ID and POST /v1/returns by (line, return ID): sending the same order again updates it. An Idempotency-Key still protects against duplicate work during a retry.

When to retry

• Retry on network errors, timeouts, 409 idempotency_key_in_use, 429 (after Retry-After) and 5xx, with exponential backoff and the same key.
• Do not retry other 4xx answers unchanged: fix the request first.