Terminal
Terminal/Skill
Helps developers make endpoints, webhooks and queue consumers safe to retry, so repeats do not charge a card or send an email twice.
By Trigger.dev
Works with
npx skills add triggerdotdev/staff-engineering-skills --skill staff-engineering-skills-idempotencyThe request was sent twice. The customer was charged twice. Before writing any operation that mutates state, ask: what happens if this runs again with the same input?
Every system faces these as normal operation, not edge cases. You cannot prevent them -- only make operations safe when they happen.
| Naturally idempotent (safe to repeat) | NOT idempotent (dangerous to repeat) |
|---|---|
SET x = 5 | SET x = x + 1 |
UPDATE status = 'paid' WHERE id = ? | INSERT INTO orders (...) |
DELETE WHERE id = ? | balance += amount |
PUT /users/123 {full body} | POST /orders {new order} |
| Upsert (INSERT ... ON CONFLICT UPDATE) | sendEmail(user, template) |
stripe.charges.create(...) |
Design for natural idempotency first. If you can express the operation as "set to this state" rather than "apply this change," it's inherently safe.
Stop and add idempotency protection if you see:
stripe.charges.create() without an idempotency key double-charges; retrying POST /orders creates duplicates.INCREMENT or INSERT without deduplication -- SQS, RabbitMQ, Kafka (at-least-once) can all deliver the same message twice.sendEmail(), sendSMS(), or any notification call without a dedup check -- the user gets two of everything.The client generates a unique key (UUID) and sends it with the request; the server detects retries by the key.
app.post("/api/orders", async (req, res) => {
const idempotencyKey = req.headers["idempotency-key"];
if (!idempotencyKey) {
return res.status(400).json({ error: "Idempotency-Key header required" });
}
// Return stored response if already processed
const existing = await db.idempotencyRecord.findUnique({ where: { key: idempotencyKey } });
if (existing?.status === "complete") {
return res.status(existing.statusCode).json(existing.responseBody);
}
// Claim key + create business data in ONE transaction (unique constraint loses the race for one of two retries)
const order = await db.$transaction(async (tx) => {
await tx.idempotencyRecord.create({ data: { key: idempotencyKey, status: "processing" } });
return tx.order.create({
data: { userId: req.user.id, items: req.body.items, total: req.body.total },
});
});
// External side effects get THEIR OWN key derived from the original
await stripe.paymentIntents.create(
{ customer: req.user.id, amount: order.total, currency: "usd" },
{ idempotencyKey: `charge-${idempotencyKey}` }
);
// Store response so duplicates get the SAME response as the original
await db.idempotencyRecord.update({
where: { key: idempotencyKey },
data: { status: "complete", statusCode: 201, responseBody: order },
});
res.status(201).json(order);
});
The three load-bearing details: the idempotency record is created in the same transaction as the business data; external APIs get their own keys derived from the original; the stored response is replayed on duplicates.
Webhook providers include a unique event ID. Record it and skip duplicates. The unique constraint on eventId also catches races between two simultaneous deliveries. Non-transactional side effects (emails) go after the dedup gate.
app.post("/webhooks/stripe", async (req, res) => {
const event = req.body;
try {
await db.$transaction(async (tx) => {
await tx.processedWebhookEvent.create({ data: { eventId: event.id, processedAt: new Date() } });
if (event.type === "payment_intent.succeeded") {
await tx.order.update({
where: { paymentIntentId: event.data.object.id },
data: { status: "paid" },
});
}
});
} catch (error) {
if (isPrismaUniqueConstraintError(error)) {
return res.json({ received: true }); // Already processed, skip
}
throw error;
}
if (event.type === "payment_intent.succeeded") {
await sendConfirmationEmail(event.data.object.metadata.userId);
}
res.json({ received: true });
});
The producer includes a unique transaction/message ID; the consumer records it in the same transaction as the work. On a real error, don't ack -- let the queue redeliver.
worker.on("message", async (msg) => {
const { transactionId, userId, amount } = JSON.parse(msg.body);
try {
await db.$transaction(async (tx) => {
// Unique constraint on transactionId prevents duplicates
await tx.processedTransaction.create({ data: { id: transactionId, processedAt: new Date() } });
await tx.account.update({ where: { userId }, data: { balance: { increment: amount } } });
});
} catch (error) {
if (isPrismaUniqueConstraintError(error)) {
await msg.ack(); // Already processed -- ack and move on
return;
}
throw error; // Real error -- don't ack, let queue redeliver
}
await msg.ack();
});
When possible, design the operation so repeating it converges on the same state -- upsert, or SET rather than INCREMENT.
// Same result whether it runs once or five times
async function setUserPreference(userId: string, key: string, value: string) {
await db.userPreference.upsert({
where: { userId_key: { userId, key } },
create: { userId, key, value },
update: { value },
});
}
Most payment/communication APIs support idempotency keys -- always pass them.
await stripe.paymentIntents.create(
{ customer: customerId, amount, currency: "usd" },
{ idempotencyKey: `order-${orderId}-charge` }
);
// Twilio: unique message SID or your own dedup. SendGrid: custom unique args. AWS SES: MessageDeduplicationId (FIFO).
If the API has no idempotency-key support, track the call yourself:
async function sendWelcomeEmail(userId: string) {
const sent = await db.sentEmail.findUnique({
where: { userId_template: { userId, template: "welcome" } },
});
if (sent) return; // Already sent
await emailService.send({ to: userId, template: "welcome" });
await db.sentEmail.create({ data: { userId, template: "welcome", sentAt: new Date() } });
}
// Dangerous: retry wrapping a non-idempotent call
await retry(() => stripe.paymentIntents.create({ amount, customer }), { retries: 3 });
// First call succeeds, response lost, retry creates a SECOND charge. Fix: pass idempotencyKey to Stripe.
// Dangerous: POST handler with no dedup -- double-click = two orders, two charges
app.post("/api/orders", async (req, res) => {
const order = await db.order.create({ data: req.body });
await chargeCustomer(order.total);
res.status(201).json(order);
});
// Fix: require and check Idempotency-Key header.
// Dangerous: queue consumer with INCREMENT -- SQS delivers twice = balance incremented twice
worker.on("message", async (msg) => {
const { userId, amount } = JSON.parse(msg.body);
await db.account.update({ where: { userId }, data: { balance: { increment: amount } } });
await msg.ack();
});
// Fix: dedup on transactionId in a single transaction.