Caching

Every API response says, in the X-Cache header, whether it came from a stored copy or was computed on the spot. Today most endpoints are computed on the spot and only a few store copies: here you see what each value means and how to prepare your client.

3 min readReviewed on October 24, 2026

What it is for

When many requests ask for the same thing in a short interval, storing the response avoids computing it again. The X-Cache header lets you see, on every response, where it came from, so you know how fresh the information is and skip the requests you do not need.

The two headers

HTTP

X-Cache:     BYPASS

X-Cache: Always present. One of HIT, MISS or BYPASS. It describes how the response was produced.
X-Cache-TTL: Only when the response used a stored copy: the seconds left before it expires. Until then, every client gets the same content. Permanent copies answer HIT without this header.

X-Cache values

Value	Meaning
`HIT`	The response came from a stored copy. If it carries `X-Cache-TTL`, it says how many seconds it stays valid.
`MISS`	A copy was looked up and was not there, so the response was generated on the spot. `X-Cache-TTL` reports the lifetime of the copy just stored.
`BYPASS`	No stored copy was involved: the response was computed on the spot. No `X-Cache-TTL` is emitted.

What to expect today

Three groups of endpoints in the reference store copies and declare HIT or MISS with X-Cache-TTL. Everything else answers X-Cache: BYPASS, as do the edge error responses (401, 404, 429, 5xx).

Endpoint	`X-Cache`	Copy lifetime
Countries: list and detail (`GET /api/v6/tools/countries` and `/{code}`)	`HIT` or `MISS`, with `X-Cache-TTL`	Up to one hour
URL shortener: link statistics and overview	`HIT` or `MISS`, with `X-Cache-TTL`	Up to 60 seconds (default)
All other endpoints and edge errors	`BYPASS`	No copy

A HIT or MISS response can be as old as its copy lifetime. That is why your client should read the header instead of assuming its value.

How to prepare your client

01
Read the header, do not assume it
If HIT arrives with X-Cache-TTL: N, the next N seconds return the same content: schedule your next call for "now + N seconds", with a small random jitter so several clients do not coincide at the same instant.
02
Log it next to the requestId
A sustained shift from BYPASS to MISS or HIT is usually the earliest signal of a behavior change, well before latency moves.
03
Do not count on immediacy
A HIT reflects the state of the world when the copy was stored. To confirm events that need immediacy, use a webhook instead of polling in a loop.

X-Cache describes the copy Hablame keeps to serve your responses. It says nothing about what your own system may store. Responses can contain information about your organization: if you keep copies on your side, do not share them across organizations or leave them in a public cache.

Example

The headers of a GET /api/v6/tools/countries response today (the country list stores copies):

200 OK

HTTP/1.1 200 OK
X-Cache:      HIT
X-Cache-TTL:  2874
X-Request-Id: b9b1704baffab211
Content-Type: application/json; charset=utf-8