POST requests accept an Idempotency-Key header:
Send the same key again within 24 hours and you get the original response back.
No second ticket is created.
Why you want this
The moment a support system collects duplicate tickets is a network timeout.
Your request arrived, the ticket was created, and the response never reached
you. Your retry logic does the only sensible thing and sends it again. Now the
customer has two tickets and your agent answers both.
An idempotency key removes the ambiguity. The retry returns the first result,
so a timeout costs you nothing.
Use one on any POST that sits behind a retry, a queue, or a webhook
handler. Those are all places where the same event can arrive twice.
Choosing a key
Any unique string. A UUID per logical operation is the usual choice.
The key must be unique to the operation, not to the attempt. Generating a
fresh key on each retry defeats the whole mechanism, because the server has
nothing to recognise. Generate it once, before the first attempt, and reuse it
for every retry of that same operation.
If you already have a natural id for the thing that caused the ticket, use it:
That way the same failed job never opens two tickets, even across process
restarts.
The window
24 hours. After that the key is forgotten, and reusing it opens a new ticket.
Long enough to cover any realistic retry, short enough that keys do not pile
up forever.
Failures are not replayed
Only a completed response is stored. If the first attempt failed with a 500
or timed out before anything was written, the retry runs for real rather than
replaying the error.
Caching failures would turn a transient blip into a permanent one for a full
day, which is the opposite of what you want from a retry path.
Which requests it applies to
POST only, which covers creating tickets and posting messages. GET is
already safe to repeat. PATCH on this API sets fields to values you supplied
rather than incrementing anything, so sending it twice lands in the same state.
