SendGrid duplicate emails: retrying a 202 that looked like a failure

TL;DR

Timeout set shorter than SendGrid's response time, so the client gives up and resends while the first request is still being accepted. Symptom: duplicate deliveries with distinct message IDs minutes apart.

Steps

1. Cause candidates:
2. Treating the 202 empty body as an error and retrying. Confirm: your logs show a 202 followed by a retry of the same content.
3. Timeout set shorter than SendGrid's response time, so the client gives up and resends while the first request is still being accepted.
4. Two code paths both firing (e.g. a webhook handler plus a cron) for the same trigger.
5. Confirmation: match duplicates by recipient + subject + timestamp proximity in email activity. Same content, different message IDs, minutes apart is the retry signature.
6. Fix:
7. Treat 202 as success, full stop. The empty body is normal.
8. Give the request a generous timeout before retrying, and retry only on transport errors or 5xx/429, never on 202.
9. Make the trigger idempotent: record that the mail was queued before calling send, and check the record first.
10. Verification: duplicates stop and each send has exactly one delivered event per recipient.

When to use

You are seeing this: Symptom: duplicate deliveries with distinct message IDs minutes apart. Use this skill when you run into "SendGrid duplicate emails: retrying a 202 that looked like a failure".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

The mail send reference: a successful request returns 202 with an empty body. The SMTP errors doc notes the temporary block for repeated bad requests. Retrying a request that already returned 202 creates duplicates, because the first request was accepted. Sources: https://docs.sendgrid.com/api-reference/mail-send/mail-send | http://sendgrid.com/docs/Glossary/emailerrormessages.html