Contract authority: OpenAPI is the machine-readable public v1 contract. This page is generated from the Privilege Integrator Pack. If prose and OpenAPI disagree, stop and contact Privilege.

10. Idempotency

All four mutating operations require header Idempotency-Key.

Rule	Behavior
Charset	A-Za-z0-9._:~-
Max length	128 (default)
Same key + same logical request	Replay prior completed response
Same key + different payload/path	409 IDEMPOTENCY_CONFLICT — do not do this
Concurrent duplicate while first still running	409 IDEMPOTENCY_IN_PROGRESS (may include Retry-After: 2)

POS guidance

1. Generate a new unique key per logical till operation (e.g. one validate attempt, one confirm for that sale).
2. On network timeout or connection drop, retry the same operation with the same key and same body — a timeout does not mean the server failed.
3. Never invent a second confirm with a new key for the same sale after an ambiguous first attempt; reuse the confirm key until you have a definitive response.
4. Do not reuse a validate key for confirm (different operation + different body).

Keys are scoped per Integration Client and operation.

---

12. Retries and timeouts

What Privilege publishes today:

Topic	Guidance
HTTP client timeout	Choose a conservative client timeout (e.g. tens of seconds). Privilege does not currently publish a mandatory client timeout SLA in OpenAPI.
Connection failure / timeout	Treat as ambiguous; retry with same Idempotency-Key + same body.
5xx / INTERNAL_ERROR	Safe to retry idempotent operations with backoff; keep the same key.
429 RATE_LIMITED	Back off and retry. Rate-limit responses use standard rate-limit headers from the limiter library where enabled; a dedicated public Retry-After policy for 429 is not separately documented beyond that. Default authenticated ceiling is on the order of 120 requests / client / minute (server-configurable).
409 IDEMPOTENCY_IN_PROGRESS	Wait and retry; response may include Retry-After: 2.
Deterministic 4xx (auth, validation, unmapped outlet, invalid token, conflict on state)	Do not blind-retry without fixing the request.

Pre-auth IP ceiling also exists (brute-force bound); do not hammer Basic auth with wrong secrets.

---