What is idempotency?

In computer science, idempotency is a property of an operation where applying it multiple times has the same final effect as applying it just once. If you send the same request to a server five times, an idempotent system ensures that the outcome on the server doesn't change after the first successful attempt.

Beyond ensuring the same result, a key characteristic of idempotent operations is that they produce no side effects with additional calls. This is a core requirement for building resilient distributed systems where intermittent network outages or timeouts might cause a client to send the same message more than once.

Analogy: Think of the "up" button on an elevator. If you press it once, the elevator is called to your floor. If you press it ten more times while waiting, the result is the same—one elevator still comes to your floor. Pressing the button multiple times doesn't summon ten separate elevators. In contrast, adding an item to a digital shopping cart is usually not idempotent. If you click the "Add to Cart" button five times, you’ll likely end up with five of that item in your basket.

Key benefits of idempotent systems

Safely retry requests after a timeout or connection drop without fear of duplicating actions (like double-charging a credit card).

Users don't need complex state tracking to know if a previous request succeeded; they can simply "retry until success."

Distributed systems can recover from crashes by replaying logs or re-sending missed messages without corrupting data.

Idempotent versus non-idempotent HTTP methods

The REST standard defines how different types of web requests should behave. Some HTTP methods are naturally "safe" or idempotent by design, meaning the specification expects them to behave predictably even when repeated. Others are designed to create new data and require extra care to make them safe for retries.

Idempotent methods (GET, PUT, DELETE)

According to RFC 9110, several standard methods are inherently idempotent. Repeating these actions should not change the state of the server beyond the initial request.

  • GET: This method retrieves data. Since it doesn't change anything on the server, you can call it a million times and the resource remains the same.
  • PUT: This method replaces a resource entirely. If you update a user’s email to "user@example.com" three times, the final state is still that the email is "user@example.com."
  • DELETE: This removes a resource. If you delete "Order #123" and then try to delete it again, the order stays deleted. The result (the order is gone) remains the same.

Non-idempotent methods (POST, PATCH)

Some methods are not idempotent because their primary job is to change data in a way that creates something new or modifies a portion of an existing record.

  • POST: Developers use POST to create new resources. Without idempotency logic, sending the same POST request twice (like "Submit Payment") would typically result in two separate records—and two charges to the customer.
  • PATCH: This method applies partial updates. While it can be made idempotent, it often isn't by default because repeating a relative change (like "add 5 to the balance") would result in a different final value each time it's called.

How to implement an idempotent API

  1. Generate a unique key: The client creates a unique string (like a UUID) and includes it in a custom HTTP header.
  2. Intercept and validate: The server checks a high-speed data store like Memorystore to see if that key has been processed recently.
  3. Handle the state: If the key is new, process the request and save the result. If it's a duplicate, return the stored result immediately without re-running business logic.

Common use cases for idempotency

Idempotency is often needed in the systems we build. In some cases, it is handled for us. In other cases, we as developers need to take action to make it happen.

The most famous example is the "double charge" problem. If a user’s browser hangs while they are paying for a flight, they might click "Pay" again. A payment API that uses an idempotency key ensures that the second click is recognized as a retry. This protects the customer's bank account and reduces the operational cost of handling refunds for duplicate transactions.

  • Developer action required: You must implement an idempotency key (often a UUID) in your API request to ensure the second click is recognized as a retry, protecting the customer’s bank account

Tools like Terraform and Ansible rely on idempotence. When you run a script to "create a 10GB storage bucket," the tool checks the current state of your cloud.

  • Handled for you: Idempotency is managed by the IaC tool itself; as a developer, you don't need to write extra logic to prevent duplicate resources

Modern web APIs often implement the Idempotency-Key header (now a standardized IETF draft) to allow developers to build more robust integrations.

  • Developer action required: When building the backend, you must implement the logic to intercept these keys, check for previous attempts, and return the cached response

An "upsert" (update or insert) is a classic idempotent database operation. Instead of a simple "Insert," an upsert says: "If this record exists, update it; if not, create it."

  • Handled for you: This logic is handled natively by the database engine, ensuring records converge to the correct state regardless of how many times the script runs

Solve your business challenges with Google Cloud

New customers get $300 in free credits to spend on Google Cloud.
Talk to a Google Cloud sales specialist to discuss your unique challenge in more detail.

Building reliable microservices on Google Cloud

Google Cloud provides several tools that make implementing these patterns easier for developers. Building on a managed platform reduces the amount of "boilerplate" code you need to write to keep your data safe.

  • Cloud Run: When you use Cloud Run to process events from Pub/Sub, remember that Pub/Sub may deliver messages more than once by default. Writing idempotent code in your Cloud Run services is a requirement to ensure your AI agents or data pipelines don't process the same event twice.
  • Note on Pub/Sub: While the default is Push-based delivery, exactly-once delivery is available for Pull-based subscriptions. It's helpful to be aware of these two types to choose the right level of complexity for your service.

Ready to build?

Learn how to deploy resilient, idempotent services on Cloud Run today.

Google Cloud