Idempotency
The response that never arrives.
A connection drops, a proxy runs into a timeout — and your program does not know whether the write happened. Without a guarantee there are two choices and both are wrong: lose the record, or create it twice.
How it works.
You choose one value per intended write — a UUID will do — and send it in the header. The first call does the work; every repeat under the same value gets the same record back, and no second one is created.
What it looks like.
The same three lines, as often as you like. On the second attempt KRONENWERK answers with the customer from the first.
POST https://kronenwerk.org/api/extern/v1/customers\nAuthorization: Bearer greif_live_…\nIdempotency-Key: 6f1c2a8e-4b3d-4a21-9d77-0c5e1f9b2a44\n\n{"name":"Kellermann Elektrotechnik GmbH","email":"buchhaltung@kellermann.de","street":"Am Sandtorkai 41","postalCode":"20457","city":"Hamburg","country":"DE"}Three rules.
Same body
You get the same record back, read the way it was read the first time.
Different body
Refused. A key stands for exactly one intention, and answering it quietly would confirm something that did not happen.
Lifetime
24 h — after that the same value counts as new work again
Why the header is required.
An optional guarantee protects exactly the callers who did not need protecting. A duplicated customer goes unnoticed until an invoice reaches the wrong copy, and by then it is weeks old.