Every queue retries. The retry is harmless if the send itself is idempotent and expensive if it is not: a customer who gets three password reset emails assumes the product is broken.
The key belongs to the message
An idempotency key derived from (recipient, template, business event) means the second, third and fourth attempt resolve to the same message. A key generated inside the worker is useless, because the worker is exactly the thing that restarts and forgets.
Where the key is enforced
Enforcement has to be server side, at the send endpoint, with a unique index and a stored response. The first call creates the message and returns its id; the retry finds the key and returns the same id with the original status. That also makes the API safe to call twice from two different services racing on the same event.
The expiry question
Keys cannot be kept forever, but they must outlive the retry window. If your queue can retry for 48 hours, a 24-hour key is not idempotent, it is a delay. Keep keys at least as long as the longest retry horizon, and longer for anything that triggers billing.
One detail that catches people
Return the original response, not a generic 200. If the first call returned 202 with a message id and the retry returns a different shape, the caller may treat it as a failure and enqueue again — the exact loop the key was meant to prevent.
Volanea accepts an idempotency key per send and replays the original response on a repeat, so retries are safe by default.
Top comments (0)