API Security

Design Idempotent Commands and Request Handling

Ensure repeated requests do not accidentally repeat important business effects.

Networks fail in ambiguous ways. A client may time out after the server commits an operation and retry because it cannot tell whether the first request succeeded. Idempotency makes these retries safe.

Identify operations that need protection

Payments, order creation, provisioning, and external notifications often need idempotency. A read request is naturally repeatable, but a command that creates a resource may not be.

Use stable idempotency keys

Accept a client-generated key scoped to the authenticated actor and operation. Store the key, request fingerprint, processing state, and final result. Reusing a key with a different request body should produce a clear conflict rather than silently returning an unrelated result.

Coordinate concurrent requests

A unique database constraint should prevent two requests from claiming the same key simultaneously. Use a transaction to create the idempotency record and persist the business outcome consistently.

Define retention

Keep keys long enough to cover realistic retry windows and operational recovery. Avoid retaining unnecessary sensitive request payloads.

Checklist

  • Identify commands with duplicate-side-effect risk.
  • Scope keys to actor and operation.
  • Enforce uniqueness in the database.
  • Reject key reuse with different input.
  • Define retention and replay behavior.
Share this page Help other developers discover this resource.