API Security

Implement Idempotency for PHP API Requests

Make retryable create and payment-style operations safe by ensuring the same client request does not create duplicate effects.

Overview

Clients retry requests when a connection times out or a response is lost. The server may have completed the first request even though the client never received its response. Idempotency keys let the server recognize a retry and return the original outcome instead of repeating the action.

Require a client key

For operations that create expensive or irreversible effects, require a high-entropy idempotency key. Scope it to the authenticated account and operation. Apply length and character limits, and reject empty or malformed keys.

Persist the result atomically

Create a table with a unique constraint over account, operation and idempotency key. Store a request fingerprint and processing state. The unique constraint prevents two concurrent requests from both claiming the same key.

Detect key reuse with different input

Hash a canonical representation of the relevant request fields. If the same key arrives with a different fingerprint, return a conflict rather than silently reusing an unrelated result. Do not include secrets or volatile headers in the fingerprint.

Coordinate side effects

A database transaction can protect database changes, but it cannot automatically make an external payment, email or third-party API call transactional. Use an outbox or provider-side idempotency support where available. Define how in-progress requests and failed operations are recovered.

Retention policy

Keep idempotency records for at least the maximum retry window promised to clients. Document expiration behavior; after a key expires, the same request may be treated as new.

Checklist

  • Scope keys to identity and operation.
  • Enforce a unique database constraint.
  • Store and compare request fingerprints.
  • Handle concurrent requests atomically.
  • Coordinate external side effects separately.
  • Document key retention and retry semantics.

References

Stripe: Idempotent Requests · RFC 9110: Idempotent Methods

Share this page Help other developers discover this resource.