API error triage route from 429 to unsafe POST retry

HTTP 429 is a queueing problem before it is a code bug. The client may have a bug, but the first response should be to slow, queue, or reschedule requests instead of immediately changing business logic.

MDN describes 429 Too Many Requests as a response for too many requests in a given amount of time and notes that a Retry-After header might indicate how long to wait. RFC 6585 defines 429 similarly and says response representations should explain the condition and may include Retry-After. GitHub REST API rate limit documentation also separates rate-limit resources and explains that search endpoints have custom rate limits separate from other REST endpoints.

A good 429 debug note should include endpoint family, authentication state, remaining limit if provided, reset time, Retry-After, concurrency, request burst size, and whether search or normal API endpoints were involved. Without those fields, teams often blame the wrong layer. The issue might be a sudden fan-out, a missing cache, a polling interval, a batch job crossing an hourly window, or a search endpoint with a separate budget.

The fix should match the evidence. If Retry-After is present, respect it. If reset headers exist, schedule around them. If several workers share one token, coordinate the queue. If users can trigger repeated searches, debounce or cache the search request. If the call is optional, degrade the feature instead of hammering the endpoint.

Treating 429 as an exception to hide is usually wrong. It is feedback from the service about pacing. The client should make that pacing visible in logs and user-facing states.

HTTP 429 is a queueing problem before it is a code bug

// COMMENTS

ON THIS PAGE