What to log when an API returns 429 Too Many Requests

When an API returns 429 Too Many Requests, log enough context to distinguish a real traffic spike from a bad retry loop, shared token, or one hot endpoint.

The minimum log record should include timestamp, endpoint, method, status code, Retry-After value, caller identity or token scope, request id, retry attempt, and local queue depth. Without these fields, a 429 incident becomes guesswork. You may know that the API asked you to slow down, but not which caller was responsible or whether your own retry code amplified the problem.

Read Retry-After before deciding the next request. MDN describes 429 as a rate-limiting response and notes that Retry-After may tell the client how long to wait. If the server sends that header, client code should respect it unless there is a documented reason not to. Ignoring it often converts a short throttle into a longer outage.

Separate idempotent and non-idempotent retries. A GET or status poll can usually be retried with backoff. A payment, account creation, email send, or write operation may need an idempotency key or a different replay policy. The log should show which category the request belongs to.

Look for synchronized callers. Cron jobs, test suites, webhooks, and page loads can all fire at the same minute. If every caller retries after the same fixed delay, the system creates waves of 429 responses. Jitter, queues, caching, and request coalescing can reduce the pressure.

A good 429 report should end with a concrete change: lower concurrency, cache a repeated read, move background jobs apart, fix a loop, add backoff, or ask the API provider for a documented quota. “It rate limited” is not enough for the next person to act.

What to log when an API returns 429 Too Many Requests

// COMMENTS

ON THIS PAGE