Idempotent operations and idempotency keys

A POST endpoint for payments or orders with no idempotency protection turns a network retry into a duplicate charge or duplicate resource creation. This is not a theoretical risk — mobile networks, load balancers, and client libraries all retry on connection failure. CWE-770 (Allocation of Resources Without Limits or Throttling) applies when duplicate submissions trigger duplicate downstream effects. PUT endpoints that increment rather than set are silently non-idempotent: calling them twice produces different state than calling them once, making any retry logic dangerous.

Ensure PUT and DELETE are idempotent by design, and add idempotency key support for critical POST operations:

// PUT must SET, not INCREMENT:
// Before (not idempotent):
await db.user.update({ credits: { increment: amount } })
// After (idempotent):
await db.user.update({ credits: amount })

// Idempotency key for critical POST operations:
const idempotencyKey = req.headers.get('Idempotency-Key')
if (idempotencyKey) {
  const existing = await db.idempotencyLog.findUnique({ where: { key: idempotencyKey } })
  if (existing) return Response.json(existing.response, { status: existing.status })
}
// Process, then store: await db.idempotencyLog.create({ key, response, status })

DELETE must return 204 on the first call and 204 or 404 on subsequent calls — never 500.