URL, HTTP & curl

API Response Headers: Interpret Retry-After Before Retrying

Interpret a Retry-After response header, distinguish seconds from HTTP dates, and apply bounded retry decisions without replaying unsafe API writes.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Treat a response header as input to a retry decision

An API response header can tell the client when another attempt may be appropriate. Retry-After is a useful example because it affects behavior after a response such as 429 or 503. Reading it correctly is only one part of deciding whether to retry the operation.

Keep the original status, request method and application context. A delay does not make a failed write safe to repeat. If the server may already have created a resource, a second POST could create another unless the endpoint offers and correctly applies an idempotency mechanism.

Parse a small, explicit subset for a controlled client

function retryDelayMs(value, nowMs = Date.now()) {
  if (typeof value !== "string" || !Number.isFinite(nowMs)) return null;
  const text = value.trim();
  if (/^\d+$/.test(text)) {
    const milliseconds = Number(text) * 1000;
    return Number.isSafeInteger(milliseconds) ? milliseconds : null;
  }
  const dateForm = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
  if (!dateForm.test(text)) return null;
  const instant = Date.parse(text);
  if (!Number.isFinite(instant) || new Date(instant).toUTCString() !== text) return null;
  return Math.max(0, instant - nowMs);
}

The function returns milliseconds or null when it cannot interpret the value. Its date branch intentionally accepts the modern IMF-fixdate spelling shown here, not every historical HTTP-date form. It checks the normalized date too, preventing a loosely parsed impossible date from silently becoming another day.

With value 12, the result is 12,000 milliseconds. With a valid HTTP date ten seconds after the supplied nowMs, it returns 10,000. A valid date in the past returns zero. A fractional number such as 1.5 is not accepted as delay-seconds by this helper.

Separate parsing from scheduling

The Retry-After reference describes delay-seconds and an HTTP-date. A parser can return a long delay that the application's scheduler should not directly hand to a short-lived timer. Use a policy limit and decide whether to defer work, show a later retry time or stop automatic attempts.

Do not cap a requested long wait to a much shorter interval and then retry early. If the instruction exceeds the application's automatic-wait budget, pause that retry path or schedule it through an appropriate persistent mechanism. Record the reason without logging a sensitive response body.

A missing or malformed header also needs a policy. It should not produce an immediate, unbounded loop. Use the documented retry strategy, an attempt limit and cancellation. If applying jitter, ensure that its interpretation does not violate the server's minimum wait instruction.

Account for the clock and the request's outcome

A date-based wait depends on the client's clock. A clock that is far ahead or behind can distort the calculated interval. The function accepts nowMs explicitly so tests can use a fixed instant and the application can make any documented clock adjustment outside the parser.

Inspect the 429 status definition and the endpoint's quota rules together. A quota might apply to an account, token, resource or other scope. Starting several independent retry loops can defeat the intended coordination even when each loop parses the header correctly.

For example, three components sharing one account should not each retry the same failed lookup at the earliest possible instant without coordination. A shared queue can retain the latest applicable wait time and let a cancelled component withdraw its work. This is application behavior; the header itself does not identify duplicate operations or manage that queue.

Keep a user's explicit retry separate from an automatic loop as well. If an earlier request is still active, a new button click should not silently start another copy. Present the current wait or cancellation state, then commit only the result belonging to the accepted request.

Verify waiting logic without sending repeated live requests

Use a local fixture and a fake or controlled clock. Check two numeric delays, a future date, a past date, an impossible date, whitespace and an oversized number. Assert that invalid inputs return null and that zero remains a valid result.

Then test the separate scheduler's attempt limit, cancellation and write policy. A parser test does not establish those properties. The Response Header Checker reviews pasted headers but does not schedule retries or assess whether a repeated write is safe.

Treat a response header as input to a retry decision

Parse a small, explicit subset for a controlled client

Separate parsing from scheduling

Account for the clock and the request's outcome

Verify waiting logic without sending repeated live requests

Related guides