Idempotency

Every mutating route that applies a relative change (balance/HP/vacation increase or decrease, inventory or stock add/remove) requires an Idempotency-Key header — a unique string you generate per logical operation (a UUID works well).

If a request with the same key, method, path, and body is retried within 24 hours, the original response is replayed instead of the mutation being applied a second time — safe to retry after a timeout or dropped connection without double-applying an increment.

A request that returns a 4xx/5xx releases its key immediately — a corrected retry (fixed validation error, or a transient server error) with the same key actually re-runs the handler rather than replaying the stale failure.

Routes that set an absolute value rather than applying a relative change — for example, PATCH /items/{itemId} or the .../set and .../clear status routes — are naturally idempotent and do not require this header.

Omitting the header on a route that requires it returns 400 with error.code: "MISSING_IDEMPOTENCY_KEY".