−50%

50% off your first month on any paid plan · code WELCOME50 · until Nov 30

Start free →
Glossary · I

What is idempotency? Safe retries for scheduled tasks

Definitionidempotency · noun

Idempotency means that running an operation more than once produces the same result as running it once.

Send the same API request twice, get the same outcome. No duplicate records, no double charges, no extra emails. The second call is a no-op.

The concept comes from mathematics (applying a function multiple times yields the same result as applying it once), but in software it's a practical engineering constraint. Any system that retries failed operations needs idempotent handlers on the receiving end, or those retries create problems instead of fixing them.

Why idempotency matters for cron jobs#

Cron jobs and scheduled webhooks run repeatedly by design. Overlap happens — a job starts before the previous run finishes, a network timeout triggers a retry, or the scheduler fires twice because of a clock sync hiccup. That's three separate ways you end up with duplicate runs. If the job's logic isn't idempotent, each creates duplicates or corrupted state.

Consider a nightly script that imports orders from an external API into your database. Without idempotency, a retry inserts the same orders again. With it, the script checks whether each order already exists before inserting. Same input, same result, no matter how many times it runs.

Common idempotency patterns#

The simplest approach is a unique key. Before processing a record, check if it's already been processed. Database unique constraints handle this at the storage level. Idempotency keys (a unique token sent with each request) handle it at the API level. Stripe, for example, accepts an Idempotency-Key header that prevents duplicate charges even if the client retries.

For scheduled tasks, the pattern is usually time-based. Process all records where updated_at falls within a window. If the job runs twice for the same window, it processes the same set and produces the same result. No duplication.

How monitoring fits in#

Making a job idempotent doesn't mean you stop monitoring it. A job that silently skips already-processed records still needs to report that it ran and finished on time. Cron job monitoring catches the case where a job doesn't run at all. Dead-letter queues catch messages that couldn't be delivered. Idempotency handles the third failure mode: the job ran more times than expected, and the extra runs shouldn't cause damage.

Cloud Cron services that trigger endpoints over HTTP are especially prone to this. At-least-once delivery means your endpoint might receive the same request twice. If it's idempotent, no harm done. If it isn't, you find out when duplicate records are already in production.

Frequently asked

Setting a database field to a specific value is idempotent: UPDATE users SET status = 'active' WHERE id = 5. Running it once or ten times produces the same result. Incrementing a counter (UPDATE users SET login_count = login_count + 1) is not idempotent, because each run changes the outcome.

GET, PUT, and DELETE are defined as idempotent in the HTTP specification. POST is not. A PUT request that sets a resource to a specific state can be safely retried. A POST that creates a new resource will create duplicates unless the server implements idempotency checks.

Use unique keys or time-window queries. Before inserting a record, check if it already exists. Process data for a specific time range so reruns cover the same set. Use database constraints (unique indexes) as a safety net. Design the job so running it twice with the same input produces the same output.

Retries and overlapping runs create side effects: duplicate database records, double email sends, repeated API charges, or corrupted aggregation totals. These bugs are hard to catch because the job technically succeeded — it just succeeded too many times.

Start monitoring in under 2 minutes.

Free plan includes 20 checks · No credit card required
Pricing Docs
Log in Start free →