Idempotency

Networks drop answers. An Idempotency-Key lets you send the same request again without doing the thing twice.

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-Key header. 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

WhenWhat happens
First timeThe request runs and its answer is kept for 24 hours.
Same key, same requestThe kept answer comes back, with the same status, and the header Idempotent-Replayed: true. Nothing runs again.
Same key, a different request409 idempotency_key_reused. Same means the same method, path and body, byte for byte.
While the first is still running409 request_in_progress. Wait a moment and try again.
The first ended in a 5xx errorNothing is kept, so the next try with the key runs afresh.
After 24 hoursThe 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