Caching

Some endpoints serve their response from a stored copy so repeated calls do not pay the cost of regenerating an identical payload. Two headers describe what happened on your call: X-Cache and X-Cache-TTL.

4 min read

Why it matters

A client polling a campaign status easily reaches tens of thousands of requests per minute. When all of them get the same response during a short interval, storing that result is the difference between an integration that scales and one that throttles itself. The header pair below lets you see the state of the stored copy, so you can skip the requests you do not need and reason about how fresh the information is.

The two headers

HTTP

X-Cache:     HIT
X-Cache-TTL: 240

X-Cache: One of HIT, MISS or BYPASS. It describes how the response was produced.
X-Cache-TTL: Seconds left before the current copy expires. Until then, every client gets the same payload.

X-Cache values

Value	Meaning
`HIT`	The response was served entirely from the stored copy. `X-Cache-TTL` says how many seconds it stays valid. Some catalogs keep permanent copies and answer `HIT` with no TTL: they stay valid indefinitely from your perspective.
`MISS`	There was no usable copy, so the response was generated on the spot and stored for the next callers. `X-Cache-TTL` reports the lifetime of the copy just written.
`BYPASS`	This endpoint stores nothing. Every call is computed in real time, typically because the payload depends on per-caller state that cannot be shared. No `X-Cache-TTL` is emitted.

What each endpoint emits

Endpoint	X-Cache	X-Cache-TTL	Notes
`GET /api/v6/utilities/ping`	`HIT` or `MISS`	seconds left	The first call after a copy expires is a `MISS`; the following ones inside the same window are `HIT`.
`GET /api/v6/tools/countries`	`HIT`	no TTL	The catalog is a permanent copy.
`GET /api/v6/tools/countries/{code}`	`HIT`	no TTL	Same as the listing.

Error responses (401, 404, 429, 5xx) always carry X-Cache: BYPASS, regardless of the endpoint.

Recommended patterns

01
Skip the requests you do not need
When X-Cache: HIT arrives with X-Cache-TTL: N, the next N seconds return the same payload. Schedule your next call for "now + N seconds", with a small random jitter so multiple clients do not sync on the refresh instant.
02
Take the state into your observability
Log X-Cache alongside the requestId. A sustained shift toward MISS is usually the earliest signal of a behavior change, well before latency moves.
03
Calibrate your expectations
A HIT reflects the state of the world when the copy was written. For dashboards and status views that is usually fine; to confirm events that need immediacy, use a webhook instead of polling.

X-Cache and X-Cache-TTL describe the copy we keep to serve your responses. They are independent from Cache-Control, which governs whether you (your browser, your client, any intermediary) may retain a copy. API responses travel with Cache-Control: no-store because they can contain organization-scoped information: that instruction is for your side of the wire, not ours.

Full example

A response served from the stored copy, with 18 seconds left before it expires:

200 OK

X-Cache:      HIT
X-Cache-TTL:  18
Content-Type: application/json

{
  "success": true,
  "data": { },
  "meta": { }
}