Caché

Toda respuesta de la API dice, en la cabecera X-Cache, si salió de una copia guardada o si se calculó en el momento. Hoy casi todos los endpoints se calculan en el momento y solo unos pocos guardan copias: aquí ves qué significa cada valor y cómo preparar tu cliente.

3 min de lecturaRevisado el 24 de octubre de 2026

Para qué sirve

Cuando muchas peticiones piden lo mismo en un intervalo corto, guardar la respuesta evita volver a calcularla. La cabecera X-Cache te deja ver, en cada respuesta, de dónde salió, para que sepas qué tan fresca es la información y evites las peticiones que no necesitas.

Las dos cabeceras

HTTP

X-Cache:     BYPASS

X-Cache: Siempre presente. Uno de HIT, MISS o BYPASS. Describe cómo se produjo la respuesta.
X-Cache-TTL: Solo cuando la respuesta usó una copia guardada: los segundos que le quedan antes de expirar. Hasta ese momento, cada cliente recibe el mismo contenido. Las copias permanentes responden HIT sin esta cabecera.

Valores de X-Cache

Valor	Significado
`HIT`	La respuesta salió de una copia guardada. Si trae `X-Cache-TTL`, dice cuántos segundos sigue vigente.
`MISS`	Se buscó una copia y no estaba, así que la respuesta se generó en el momento. `X-Cache-TTL` indica la vida de la copia recién guardada.
`BYPASS`	No hubo copia de por medio: la respuesta se calculó en el momento. No se emite `X-Cache-TTL`.

Qué esperar hoy

Tres grupos de endpoints de la referencia guardan copias y declaran HIT o MISS con X-Cache-TTL. El resto responde X-Cache: BYPASS, igual que las respuestas de error del borde (401, 404, 429, 5xx).

Endpoint	`X-Cache`	Vigencia de la copia
Países: lista y detalle (`GET /api/v6/tools/countries` y `/{code}`)	`HIT` o `MISS`, con `X-Cache-TTL`	Hasta una hora
Acortador: estadísticas de un enlace y resumen	`HIT` o `MISS`, con `X-Cache-TTL`	Hasta 60 segundos (por omisión)
Los demás endpoints y los errores del borde	`BYPASS`	No hay copia

Una respuesta con HIT o MISS puede tener hasta la vigencia de su copia de antigüedad. Por eso conviene que tu cliente lea la cabecera en lugar de suponer su valor.

Cómo preparar tu cliente

01
Lee la cabecera, no la supongas
Si llega HIT con X-Cache-TTL: N, los próximos N segundos devuelven el mismo contenido: agenda tu siguiente llamada para "ahora + N segundos", con una pequeña variación aleatoria para que varios clientes no coincidan en el mismo instante.
02
Regístrala junto al requestId
Un cambio sostenido de BYPASS a MISS o HIT suele ser la señal más temprana de un cambio de comportamiento, mucho antes de que se mueva la latencia.
03
No cuentes con la inmediatez
Un HIT refleja el estado del mundo en el momento en que se guardó la copia. Para confirmar eventos que requieren inmediatez, usa un webhook en lugar de consultar en bucle.

X-Cache describe la copia que Hablame mantiene para servir tus respuestas. No dice nada de lo que tu propio sistema puede guardar. Las respuestas pueden contener información de tu organización: si guardas copias en tu lado, no las compartas entre organizaciones ni las dejes en una caché pública.

Ejemplo

Las cabeceras de una respuesta de GET /api/v6/tools/countries hoy (la lista de países guarda copias):

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