What is cached
Coverage areas are the same for everyone and change rarely, so the edge holds them far longer than
any one browser does. Public tracking is the opposite: it changes as a parcel moves, so it is kept
fresh for seconds — long enough to absorb a recipient refreshing the page, short enough that a
status change surfaces quickly.
Authentication and rate limiting run on every request, including one answered from cache. A
cached response is never a way past either, and the rate-limit headers are recalculated per
request rather than served from the stored copy.
Revalidation
Every cacheable response carries anETag, a short fingerprint of the body. Send it back on the
next request as If-None-Match and an unchanged resource answers 304 Not Modified with no body
at all.
304 settles that in a few bytes instead of resending the
whole timeline.
Cache entries are keyed on the canonical URL, with query parameters sorted, so ?a=1&b=2 and
?b=2&a=1 share one entry rather than each causing a miss.
Stale responses during an incident
Cached responses carrystale-if-error. If the origin cannot answer, a cached copy that has
passed its freshness window may still be served for the period in the table above, rather than the
request failing outright. Coverage areas tolerate an hour of this because a coverage list an hour
old is still substantially correct; tracking allows sixty seconds, because stale delivery status
stops being useful quickly.
This applies to responses that were cached before the failure. A resource nobody had requested has
nothing stale to fall back on, and uncached endpoints — every write, and everything account-specific
— are unaffected: they report the error.
stale-while-revalidate lets a slightly-stale copy answer immediately while a fresh
one is fetched in the background, so the cost of an expiry is not paid by whoever happens to
arrive first.
Rate limits
Limits are per key, per minute, in a fixed window:
Public tracking is the one unauthenticated surface, so it is limited by client address instead —
there is no key to attribute it to. Test keys are held lower deliberately: a test integration that
runs away should be stopped by its own environment rather than by a live limit.
Every response reports
X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, the
last being the epoch second the window resets. Over the limit, the response is 429 and its body
carries retry_after in seconds.
Retries that do not duplicate
A write can be retried safely with anIdempotency-Key; a repeat returns the original result
instead of creating a second record. The mechanics are in
Request Lifecycle.

