Concepts

Idempotency

A retry never creates twice: every creating POST carries an Idempotency-Key.

Every POST that creates a record requires an Idempotency-Key header: 1 to 100 visible ASCII characters, such as a UUID, new for each request. The reference marks those operations.

Sent again with the same method, path and body within 24 hours, the first answer is replayed with Idempotent-Replayed: true, and nothing is done twice.
Sent with a different request, it is refused 422 IDEMPOTENCY_KEY_REUSED.
Missing or malformed: 400 IDEMPOTENCY_KEY_REQUIRED or IDEMPOTENCY_KEY_INVALID.
A create runs in one transaction with the record of its answer: a refusal leaves nothing behind, and the same key may be used again for the corrected request.

http

HTTP/1.1 201 Created
Idempotent-Replayed: true
{ …the first answer, unchanged… }

Retrying well

Create the key when you build the request, store it with the request, and reuse it for every retry of that request — after a timeout, a dropped connection or a 5xx. Only a new request gets a new key. Actions on existing documents need no key: they are safe to repeat on their own (Conventions).

The legacy POST /bills keeps its own replay, on the vendor’s reference, and takes the header only optionally.