Idempotency

Networks fail. To retry a write without doing it twice, send an Idempotency-Key header on POST and PUT:

POST /v1/sales HTTP/1.1
Host: api.europlaybook.com
Idempotency-Key: 6f1c2d0e-sales-2026-10

• The key is 1 to 200 printable characters; anything else is 400 invalid_idempotency_key. Use a unique value per logical operation, for example a UUID or your batch id.
• The first successful (2xx) response is kept for 24 hours, per API key. A retry with the same key and the same method, path and body within that time gets the same response again, with the header Idempotent-Replayed: true, without doing the work again.
• The same key with a different request is 409 idempotency_key_reused.
• Errors are not kept, so a request that failed can be retried with the same key.
• After 24 hours the same key starts a new operation.

Natural keys

Some endpoints are idempotent by design, also without the header:

Endpoint	Natural key
POST /sales	external_id per line: a line sent again is updated or left unchanged, never counted twice
PUT /products/by-sku/{sku}	The SKU: creates the product once (201), then updates it (200)
PUT /products/{id}/profiles/{regime}	The product and regime: creates or changes the product’s own profile for that regime (as a proposal)

Use the header anyway on POST. It also covers packaging proposals, which have no natural key: without it, a retried proposal adds its lines twice.