Caching

Some endpoints serve their response from an internal cache so that repeated calls don't pay the cost of regenerating an identical payload. Two response headers describe what happened for your specific call: X-Cache and X-Cache-TTL.

Why this matters

A client polling the status of a campaign easily reaches tens of thousands of requests per minute. When every caller receives the same answer for a short window, caching that answer is the difference between an integration that scales and one that throttles itself. The pair of headers below lets your client see the cache state explicitly, so you can avoid the requests you don't need and reason about how fresh the data is.

The two headers

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

Header	Meaning
`X-Cache`	One of `HIT`, `MISS` or `BYPASS`. Describes how the response was produced.
`X-Cache-TTL`	Seconds remaining before the current cached entry expires and the next caller triggers a refresh. Until then, every caller receives the same payload.

X-Cache values

✓

HIT: the response was served entirely from the cache. X-Cache-TTL indicates how many seconds the entry will keep being served before it expires. Some catalog endpoints hold permanent entries and emit HIT without a TTL; those snapshots remain valid indefinitely from your perspective.

MISS: there was no usable entry in the cache, so the response was generated fresh and stored for subsequent callers. X-Cache-TTL indicates the lifetime of the entry that was just written.

○

BYPASS: this endpoint does not cache its responses. Every call is computed in real time, typically because the payload depends on per-caller state that cannot be shared. X-Cache-TTL is not emitted.

What each endpoint emits

Endpoint	X-Cache	X-Cache-TTL	Notes
`GET /api/v6/utilities/ping`	`HIT` or `MISS`	seconds remaining	The first call after a cached entry expires is a `MISS`; subsequent calls within the same window are `HIT`s.
`GET /api/v6/tools/countries`	`HIT`	-	The catalog is a permanent cache entry. No TTL header.
`GET /api/v6/tools/countries/{code}`	`HIT`	-	Same as the list endpoint.

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

Recommended client patterns

Skip the requests you don't need. When X-Cache: HIT is paired with X-Cache-TTL: N, the next N seconds will return the same payload. Schedule your next call for now + N seconds (add a small random jitter so multiple clients don't synchronize on the refresh instant).
Track cache state in observability. Log X-Cache alongside the request id. A sudden sustained shift toward MISS is often the earliest signal of a change in cache behavior, well before tail latency moves.
Calibrate SLA expectations. A HIT reflects the state of the world as of when the entry was written. For dashboards and status views that is normally fine; for confirming events that demand immediacy (such as one-time-code arrival), use a webhook rather than polling.

X-Cache and X-Cache-TTL describe the cache that we maintain to serve your responses. They are independent from Cache-Control, which governs whether you (your browser, your client, any proxy between us) may retain a copy of the response. API responses ship with Cache-Control: no-store because they may carry information scoped to your organization; that instruction is for your side of the wire, not ours.

Wire example

A response served from cache, with 18 seconds remaining before the entry expires:

200 OK

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

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