Questions · Updated 2026-09-28

What does idempotency_payload_mismatch mean?

idempotency_payload_mismatch means the same Idempotency-Key arrived on POST /emails, or another write, with a different body than the first time, so nothing ran. Retry with the exact body the key was first used with to get the original response back, or send a new key for a new request; the sibling idempotency_in_flight is the retryable one.

idempotency_payload_mismatch means a request reused an Idempotency-Key with a different payload than the request that first carried it, and nothing ran. In the error catalogue the message is "Same Idempotency-Key was used with a different payload." and the fix is "Reuse the exact same body for retries, or send a new Idempotency-Key for a new request." It is not retryable. It arises on any write that takes the header, POST /emails and POST /emails/batch most often.

What is compared

The header's description on POST /emails says "Send the same key with the same body and the original response is replayed instead of the work happening twice. Keys are 1-256 characters and are remembered for 7 days." and continues "the same key with a different body returns 409 idempotency_payload_mismatch (Resend: invalid_idempotent_request)." The comparison covers the body, the query string and the path, for the same account on the same route. So a body with a timestamp regenerated on each attempt, a template variable that changed between attempts, a field your retry added, or a batch in which one row differs, each produce this code. One key belongs to one route, so a key used on POST /emails is a fresh key on POST /emails/batch.

The sibling code

idempotency_in_flight is the other refusal this header produces, with the same status. Its message is "A request with this Idempotency-Key is still in progress." and its fix is "Wait and retry with the same Idempotency-Key to receive the original response." It is retryable and carries retry_after_seconds. This one is not, because waiting cannot make two different bodies the same.

What to do, and what not to

Decide which request you meant. If it is a retry of the first, send the first body again, exactly, and the stored response is replayed; for POST /emails that is the original id, which GET /emails/{id} then reads. If it is a new send, give it a new key. Do not resend the changed body under the old key: it fails the same way until the key is forgotten, 7 days after it was first seen. Do not start minting a key per attempt to make the code go away: a key nobody reuses protects nothing, and a retry after a timeout then sends twice. Name the key after the action, so the body that belongs to that action is the only body that ever carries it; how to stop your code from sending the same email twice has the naming pattern. On POST /emails/batch one key covers the whole array, so the retry must be the same array.

curl -sS -X POST https://api.agentisend.com/emails \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from":"billing@yourdomain.com","to":"customer@example.com"}'
201
{
  "id": "9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42",
  "simulated": true,
  "warnings": []
}
Response

Next