REFERENCE DESK / HEADERS06 NOTES
The answer is usually
in the headers.
Rate budget, authentication challenge, cache validator, and CORS policy all arrive as header fields.
What this section covers
Response bodies explain failures to humans. Headers explain them to clients. A retry policy that ignores Retry-After is guessing; a cache layer that ignores ETag re-downloads unchanged payloads; a CORS debugging session that ignores Vary chases a browser cache instead of a server policy.
These notes cover the exact parsing rules — including the ambiguous cases, like Retry-After carrying either delta-seconds or an HTTP-date, and rate-limit resets arriving as either an epoch timestamp or a relative offset — and what to do when a provider’s implementation disagrees with the specification.
HTTP and API 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: 120
- Retry-After: Wed, 21 Oct
- HTTP-date
RateLimit-Limit, Remaining, and Reset: calculate a safe request pace
Interpret standardized and X-RateLimit API response headers, epoch resets, delta resets, multi-window policies, and inconsistent provider implementations.
- RateLimit-Limit
- RateLimit-Remaining
- RateLimit-Reset
Idempotency-Key header: scope, retention, and payload fingerprints
Design API idempotency keys that prevent duplicate writes without hiding payload changes, tenant collisions, or stale operation results.
- Idempotency-Key
- duplicate payment prevention
- payload fingerprint
WWW-Authenticate header: read the API authentication challenge
Parse Bearer and Basic authentication challenges, realms, OAuth token errors, scope hints, and multiple WWW-Authenticate values.
- WWW-Authenticate
- Bearer error=invalid_token
- realm
Access-Control-Allow-Origin: exact origins, wildcard, Vary, and credentials
Configure Access-Control-Allow-Origin safely for public APIs, credentialed requests, allowlists, CDN caches, and preflight responses.
- Access-Control-Allow-Origin
- Vary: Origin
- credentials include
ETag and If-None-Match for API caching and safe writes
Use strong and weak ETags for conditional API reads, 304 responses, optimistic concurrency with If-Match, and lost-update prevention.
- ETag
- If-None-Match
- If-Match
RELATED WORKBENCHES04
Reproduce it locally.
These tools take the same evidence the notes above describe and compute the result in your browser tab.
Layered verdict, evidence, redaction warnings, and next checks
Open incident decoder →T02CORS preflight request simulatorPreflight requirement, exact failure reasons, and corrected response policy
Open cors preflight lab →T03API rate-limit header analyzerRemaining budget, reset time, safe pace, and header conflicts
Open rate-limit analyzer →T04Exponential backoff and idempotency plannerAttempt timeline, cumulative wait, and replay-risk notes
Open retry planner →Section FAQ
Before you dig in
Are header names case-sensitive?
No. HTTP field names are case-insensitive, and HTTP/2 and HTTP/3 lower-case them on the wire. Compare header names case-insensitively; the values are what carry meaning.
Which rate-limit headers should a new API emit?
Prefer the standardised RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset fields, and send Retry-After on every 429 and 503. The X-RateLimit variants remain widely deployed, so clients should read both.
CONTINUERELATED SECTIONS
Retry policy, idempotency, pagination, and error shape are architecture decisions, not implementation details.
Open section →Error deskAPI error indexStatus codes are the first branch. Provider codes, headers, and request state narrow the repair.
Open section →Workbench indexAll six APITC toolsDecode, simulate, analyse, plan, diff, and compile — locally.
Open section →