APIForge
API-DESIGN

What is Idempotency?

In HTTP APIs, an operation is idempotent if executing it multiple times with the same parameters produces the exact same side-effect state on the server as executing it a single time.

Detailed Explanation

According to RFC 9110, HTTP methods GET, HEAD, PUT, DELETE, and OPTIONS are inherently idempotent. Executing GET /users/100 five times returns the same data without altering server state. In contrast, POST is non-idempotent. To make POST operations idempotent (e.g. payment processing or order creation), APIs use an Idempotency-Key HTTP request header stored in a fast key-value database like Redis with a 24-hour TTL.

Code Example

http
POST /v1/payments HTTP/1.1
Host: api.example.com
Authorization: Bearer jwt_token_xyz
Idempotency-Key: 7b928374-4b10-482a-912f-981249120491
Content-Type: application/json

{
  "amount": 5000,
  "currency": "USD"
}

Idempotent POST request using an Idempotency-Key header

Common Mistakes to Avoid

  • Designing PUT endpoints that mutate state non-deterministically (e.g., incrementing counter values)
  • Assuming POST requests are idempotent without implementing an Idempotency-Key header
  • Returning 500 Internal Server Errors when a duplicate idempotent request is received instead of replaying the original 200/201 cached response payload

Audit HTTP Method Semantics with APIForge

Paste any OpenAPI specification URL or YAML file into APIForge for instant 0-100 quality scoring, schema linting, and zero-CORS proxy testing.

Try Tool Now →
Share:𝕏 Postin Share

Frequently Asked Questions

Is HTTP DELETE idempotent?
Yes. Deleting a resource for the first time removes it (returning 200 or 204). Calling DELETE on that same resource ID again leaves the server in the exact same state (returning 404 or 204), so the net side-effect remains identical.
How should API servers handle duplicate Idempotency-Keys?
When a server receives a request with an Idempotency-Key it has already processed, it should skip executing the payment logic and immediately return the exact cached response body and status code from the first request.