SendGrid 429 too many requests: read the rate-limit headers and back off

TL;DR

Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on the 429 response. Reset is a unix timestamp: sleep until then instead of retrying blindly.

Steps

1. Symptom: 429 with an errors entry saying too many requests.
2. Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on the 429 response. Reset is a unix timestamp: sleep until then instead of retrying blindly.
3. Back off with jitter. Immediate retries on a 429 just burn your remaining budget.
4. For bulk mail, batch recipients into fewer requests (up to 1000 personalizations per mail send) instead of one request per recipient.
5. Over SMTP, respect the connection limits too: 5k messages per connection, 10k concurrent connections from one server. Reuse connections.
6. If 429s persist at modest volume, check for a runaway loop or a second client sharing the key, not a SendGrid problem.
7. 429 is not a 403. A 429 says slow down; a 403 says you are not allowed. Different headers, different fix.

When to use

You are seeing this: Symptom: 429 with an errors entry saying too many requests. Use this skill when you run into "SendGrid 429 too many requests: read the rate-limit headers and back off".

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 rate limits doc: every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; exceeding the limit returns 429 with a 'too many requests' errors entry. The SMTP doc adds SMTP-side limits: 5k messages per connection, 10k concurrent connections per server. Sources: https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/rate-limits | https://github.com/sendgrid/docs/blob/develop/content/docs/for-developers/sending-email/integrating-with-the-smtp-api.md