HTTP header reference
Retry-After header: seconds vs HTTP date
Parse Retry-After safely when an API returns delta-seconds or an HTTP-date, then combine it with bounded backoff and clock-skew handling.
Retry-After has two legal shapes: a non-negative number of seconds or an HTTP date. Keep both cases in the parser. A date form depends on clock accuracy; a seconds form is relative. For rate limits, it is usually the earliest provider-approved retry, not an instruction to retry forever.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Detect the form
Accept only a valid non-negative number or a parseable HTTP date; do not treat arbitrary text as zero.
- 02
Clamp clock skew
For a past date caused by skew, use zero only after recording the discrepancy and applying your minimum retry floor.
- 03
Combine policies
Use the larger of provider timing and your current backoff delay, then apply idempotency and attempt limits.
const delay = Number(headers["retry-after"]) * 1000;
delay = numeric ? seconds*1000 : max(0, Date.parse(value)-Date.now())
- 100
- window limit
- 0
- remaining
- 17s
- Retry-After
- 0
- safe req/s
Precedence Honor Retry-After when supplied. Treat reset and remaining fields as pacing evidence, not permission to burst.
Clock form X-RateLimit-Reset is often epoch seconds; the standardized RateLimit-Reset field may represent delta-seconds depending on the provider implementation.
No account · no upload · no endpoint calledOpen the full rate-limit analyzer and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every Retry-After response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the MDN — Retry-After. Recheck your pinned provider/API version before production deployment.