{"head":{"title":"What Is Idempotency in APIs? Definition | OceanLab","description":"An idempotent operation has the same effect whether it runs once or many times. Why it matters for payments and retries, idempotency keys and mistakes.","canonical":"https://oceanlab.in/glossary/idempotency"},"crumbs":[{"name":"Home","path":"/"},{"name":"Glossary","path":"/glossary"},{"name":"idempotency","path":"/glossary/idempotency"}],"slug":"idempotency","term":"Idempotency","aka":["idempotent","idempotency key"],"category":"System design","short":"The property of an operation that has the same effect whether it runs once or several times, so it is safe to retry.","body":[["In HTTP, RFC 9110 calls a method idempotent if several identical requests have the same intended effect as one. PUT and DELETE are idempotent by definition; POST is not. Setting a value to 5 is idempotent. Adding 5 is not."],["For actions that are not naturally idempotent, such as charging a card, APIs use an idempotency key: a unique ID the client sends with the request. The server stores the result for that key and returns it again if the same key comes back, instead of charging twice."]],"why":["Networks drop responses, users double-click and systems retry. Without idempotency, each retry can create a duplicate order, payment or email. Retries are built into ",{"href":"/glossary/webhook","text":"webhooks"},", queues and mobile apps, so this matters everywhere money or messages move."],"example":["A mobile app sends a pay request, but the connection drops before the reply. The app retries with the same idempotency key. The server sees the key, finds the payment already succeeded and returns that result. The customer is charged once."],"inBuild":["We give every create action that matters an idempotency key, store keys with their results for a set period, and make queue consumers and ",{"href":"/glossary/etl","text":"ETL"}," steps safe to re-run. Database unique constraints back this up, so duplicates fail even if code gets it wrong."],"mistakes":[["Generating a new key on each retry, which defeats the point."],["Checking for duplicates in code without a unique constraint, which fails under load."],["Treating the key as done before the action finishes, so a crash mid-way loses it."]],"related":[{"href":"/glossary/webhook","label":"Webhook","detail":"An HTTP request one system sends to a URL you choose as soon as an event happens, so you do not have to keep asking."},{"href":"/glossary/message-queue","label":"Message queue","detail":"A buffer that holds messages, such as tasks or events, until a worker is ready to process them, so the sender does not have to wait."},{"href":"/glossary/event-driven-architecture","label":"Event-driven architecture","detail":"A way of designing software where parts of the system publish events about what happened, and other parts react to them on their own."},{"href":"/glossary/rate-limiting","label":"Rate limiting","detail":"Capping how many requests a user, API key or address can make in a given time, to protect a system and share capacity fairly."},{"href":"/glossary/etl","label":"ETL (extract, transform, load)","detail":"A data pipeline that pulls data out of source systems, cleans and reshapes it, and loads it into a destination such as a data warehouse."}],"tools":[{"href":"/tools/payment-processing-fee-calculator","label":"Payment processing fee calculator","detail":"Free tool"},{"href":"/tools/fintech-app-cost","label":"Fintech app cost","detail":"Free tool"}],"links":[{"href":"/software/payments","label":"Software for payments","detail":"Payment systems and the compliance work they bring."},{"href":"/software/banking","label":"Software for banking","detail":"Banking systems, controls and regulation."}],"sources":[{"title":"RFC 9110, HTTP Semantics, section 9.2.2 Idempotent Methods (IETF)","url":"https://www.rfc-editor.org/rfc/rfc9110#section-9.2.2","checkedAt":"2026-10-25"}],"legal":false,"updatedAt":"2026-10-25"}