Why it matters
Say you create a checkout session and the connection drops before the answer arrives. Did EOS hold the tickets? Without a key you cannot tell, and trying again might hold them twice. With the same Idempotency-Key on both tries, the second gets the first one’s answer and nothing more happens.
How to use it
- Make a new random value for each action you mean to do once, such as a UUID, and send it as the
Idempotency-Keyheader. Up to 255 characters. - If you get no answer, or a
5xx, send exactly the same request again with the same key. - Keys belong to the API key that sent them: two systems never clash.
import { randomUUID } from "node:crypto";
const idem = randomUUID(); // one per action, kept until it succeeds
async function holdTickets(body, tries = 3) {
for (let i = 1; ; i++) {
try {
const res = await fetch("https://eos.aveoevents.com/api/v1/checkout/sessions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.EOS_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idem,
},
body: JSON.stringify(body),
});
if (res.status < 500) return await res.json();
} catch {
// no answer: safe to try again with the same key
}
if (i === tries) throw new Error("EOS did not answer");
await new Promise((r) => setTimeout(r, 500 * 2 ** i));
}
}What EOS does
| When | What happens |
|---|---|
| First time | The request runs and its answer is kept for 24 hours. |
| Same key, same request | The kept answer comes back, with the same status, and the header Idempotent-Replayed: true. Nothing runs again. |
| Same key, a different request | 409 idempotency_key_reused. Same means the same method, path and body, byte for byte. |
| While the first is still running | 409 request_in_progress. Wait a moment and try again. |
| The first ended in a 5xx error | Nothing is kept, so the next try with the key runs afresh. |
| After 24 hours | The key is forgotten and can run as new. |
Errors from your side (4xx) are kept like successes: fix the request and send it with a new key.
Endpoints that take a key
POST /events/{id}/publishPublish an eventPOST /events/{id}/unpublishUnpublish an eventPOST /checkout/sessionsCreate a checkout sessionPOST /checkout/sessions/{id}/completeComplete a checkout sessionPOST /orders/{id}/cancelCancel an orderPOST /orders/{id}/refundRefund an orderPOST /orders/{id}/mark-paidMark an order paidPATCH /events/{id}/attendees/{attendee_id}Update a guestPOST /discount-codesCreate a discount codePOST /enquiriesSend an enquiryPOST /webhook-endpointsAdd an endpoint
Other endpoints ignore the header. Reading is always safe to repeat.