What is Idempotency Key?
A unique token sent with requests to ensure the same operation is processed only once.
Definition
An idempotency key is a unique identifier (typically a UUID) included in an HTTP request header or body that allows the server to recognize and deduplicate repeated requests. If a client sends the same request twice with the same idempotency key — due to a retry after a timeout, for example — the server processes it only once and returns the cached result for the duplicate. This is critical for operations that must not be repeated, like payment processing or data creation.
Simple Analogy
Like a receipt number for a bank deposit — if you accidentally hand the teller the same deposit slip twice, they check the receipt number and say "this was already processed" instead of depositing the money twice.
Why It Matters
Cron jobs with retries can inadvertently send the same request multiple times. Without idempotency keys, each retry might create duplicate records, send duplicate emails, or process duplicate payments. CronJobPro supports custom headers, allowing you to include idempotency keys in your job configuration to ensure retries are safe.
How to Verify
Review your endpoint for idempotency key support — check for an "Idempotency-Key" or "X-Request-ID" header in the API documentation. In CronJobPro, configure custom headers to include a unique key per execution. Test by sending the same request twice with the same key and verifying only one operation is processed.
Common Mistakes
Using the same idempotency key for different operations (each unique operation needs a unique key). Not implementing server-side key storage, making the keys meaningless. Setting idempotency key expiration too short (keys expire before retries happen) or never expiring them (consuming storage indefinitely).
Best Practices
Generate a unique idempotency key (UUID v4) for each logical operation. Store processed keys server-side with the operation result. Return the cached result for duplicate keys. Set key expiration to match your maximum retry window. In CronJobPro, use execution-unique identifiers in custom headers as idempotency keys.
HTTP Methods Guide
Learn about HTTP methods
Try it free →Frequently Asked Questions
What is Idempotency Key?
An idempotency key is a unique identifier (typically a UUID) included in an HTTP request header or body that allows the server to recognize and deduplicate repeated requests. If a client sends the same request twice with the same idempotency key — due to a retry after a timeout, for example — the server processes it only once and returns the cached result for the duplicate. This is critical for operations that must not be repeated, like payment processing or data creation.
Why does Idempotency Key matter for cron jobs?
Cron jobs with retries can inadvertently send the same request multiple times. Without idempotency keys, each retry might create duplicate records, send duplicate emails, or process duplicate payments. CronJobPro supports custom headers, allowing you to include idempotency keys in your job configuration to ensure retries are safe.
What are best practices for Idempotency Key?
Generate a unique idempotency key (UUID v4) for each logical operation. Store processed keys server-side with the operation result. Return the cached result for duplicate keys. Set key expiration to match your maximum retry window. In CronJobPro, use execution-unique identifiers in custom headers as idempotency keys.
Related Terms
Idempotency
The property where executing a job multiple times produces the same result as executing it once.
Retry
Automatically re-executing a failed job to recover from transient errors.
Request Header
Key-value metadata sent with an HTTP request to provide context like authentication and content type.
Webhook Delivery
The process of sending an HTTP callback to a destination URL when a triggering event occurs.
HTTP Method
The verb (GET, POST, PUT, DELETE, etc.) that defines the type of action an HTTP request performs.