Most retry implementations—including BullMQ, custom wrappers, and managed queues—treat every non-2xx HTTP response as an identical failure. Each attempt increments the retry counter, applies backoff, and after N attempts moves the job to a dead-letter queue (DLQ).
However, a 429 status code indicates rate limiting, not a failure. The downstream service explicitly tells the client when to retry, often via a Retry-After header. Counting a 429 as a failed attempt means sustained rate limiting can move valid jobs to the DLQ, while the actual error budget—intended for 500s, timeouts, and connection resets—remains unused.
An alternative approach treats 429 (and similarly 503/529) as deferrals rather than failures: honor Retry-After, requeue the job, and do not decrement the retry count. This preserves the retry budget for genuine errors.
Ceilings for Deferred Jobs
A deferral strategy requires safeguards to prevent indefinite requeuing. Two ceilings are commonly used:
- Wall-clock deadline: A job expires after a fixed time (e.g., 24 hours) regardless of deferral count.
- Maximum defer count: A separate limit on how many times a job can be deferred.
When a job exceeds the defer ceiling, it moves to the DLQ with a distinct reason—separate from "out of retries." This distinction matters because exceeding retries suggests the downstream is broken, while exceeding deferrals suggests the service has been unusable long enough to be treated as broken.
Monitoring and Visibility
Deferred jobs are invisible in standard failure metrics. They do not trigger alerts or appear as failures, so a queue can remain undrained while appearing healthy. This requires dedicated state tracking and alerts for deferred jobs, rather than folding them into "pending" or "processing" counts.
Distinguishing 503 from 429
503 Service Unavailable is more ambiguous than 429. It may indicate temporary overload, maintenance, or a gateway issue. Some implementations lump 503 with 429 as deferrals, but the ambiguity means additional context (e.g., presence of Retry-After, service health checks) may be needed to decide whether to defer or count it as a failure.
