Skip to main content

idempotency_conflict

You reused an Idempotency-Key with a body that differs from the one it was first used with. Nothing was sent, because doing so would make the key meaningless.

Status: 409

{
  "status": 409,
  "type": "idempotency_conflict",
  "message": "Idempotency-Key has already been used with a different request body",
  "request_id": "req_01J8K2P...",
  "doc_url": "https://docs.epostix.com/errors/idempotency_conflict"
}

Keys are remembered for 24 hours, per workspace and per endpoint.

Why you got this​

  • A key is derived from something not unique per send, such as a user id or a date.
  • The body changed between the original attempt and the retry, often because a timestamp or a generated token is embedded in it.
  • Two different logical sends collided on the same key.

How to fix it​

Derive the key from the thing you are reacting to. order-4821-welcome is stable across a process restart and a queue redelivery. A user id alone is not, because that user will get more than one email.

If the body legitimately changed, this is a different send and it needs a different key.

Treat this error as a signal rather than an obstacle: it means something in your code is reusing a key it should not, and the alternative to being told is a silently suppressed email.

Is it safe to retry​

Not with the same key and body. Either restore the original body, or pick a new key for what is genuinely a new request.

See Idempotency for how to choose keys that hold up.