Caché

Algunos endpoints sirven su respuesta desde una copia guardada para que las llamadas repetidas no paguen el costo de regenerar un contenido idéntico. Dos headers describen lo que pasó en tu llamada: X-Cache y X-Cache-TTL.

4 min de lectura

Por qué importa

Un cliente que consulta el estado de una campaña alcanza fácilmente decenas de miles de peticiones por minuto. Cuando todas reciben la misma respuesta durante un intervalo corto, guardar ese resultado es la diferencia entre una integración que escala y una que se autolimita. El par de headers de abajo te deja ver el estado de la copia guardada, para evitar las peticiones que no necesitas y razonar sobre qué tan fresca está la información.

Los dos headers

HTTP

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

X-Cache: Uno de HIT, MISS o BYPASS. Describe cómo se produjo la respuesta.
X-Cache-TTL: Segundos que le quedan a la copia actual antes de expirar. Hasta ese momento, cada cliente recibe el mismo contenido.

Valores de X-Cache

Valor	Significado
`HIT`	La respuesta se sirvió íntegramente desde la copia guardada. `X-Cache-TTL` dice cuántos segundos sigue vigente. Algunos catálogos mantienen copias permanentes y responden `HIT` sin TTL: siguen válidas de forma indefinida desde tu perspectiva.
`MISS`	No había una copia utilizable, así que la respuesta se generó al momento y se guardó para los siguientes clientes. `X-Cache-TTL` indica la vida útil de la copia recién escrita.
`BYPASS`	Este endpoint no guarda copias. Cada llamada se calcula en tiempo real, normalmente porque el contenido depende de estado propio de cada cliente que no se puede compartir. No se emite `X-Cache-TTL`.

Lo que emite cada endpoint

Endpoint	X-Cache	X-Cache-TTL	Notas
`GET /api/v6/utilities/ping`	`HIT` o `MISS`	segundos restantes	La primera llamada tras expirar una copia es `MISS`; las siguientes dentro de la misma ventana son `HIT`.
`GET /api/v6/tools/countries`	`HIT`	sin TTL	El catálogo es una copia permanente.
`GET /api/v6/tools/countries/{code}`	`HIT`	sin TTL	Igual que el listado.

Las respuestas de error (401, 404, 429, 5xx) siempre llevan X-Cache: BYPASS, sin importar el endpoint.

Patrones recomendados

01
Evita las peticiones que no necesitas
Cuando X-Cache: HIT viene 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 se sincronicen en el instante del refresco.
02
Lleva el estado a tu observabilidad
Registra X-Cache junto al requestId. Un cambio sostenido hacia MISS suele ser la señal más temprana de un cambio de comportamiento, mucho antes de que se mueva la latencia.
03
Calibra tus expectativas
Un HIT refleja el estado del mundo en el momento en que se escribió la copia. Para paneles y vistas de estado normalmente está bien; para confirmar eventos que requieren inmediatez, usa un webhook en lugar de consultar en bucle.

X-Cache y X-Cache-TTL describen la copia que nosotros mantenemos para servir tus respuestas. Son independientes de Cache-Control, que gobierna si tú (tu navegador, tu cliente, cualquier intermediario) puedes retener una copia. Las respuestas de la API viajan con Cache-Control: no-store porque pueden contener información de tu organización: esa instrucción es para tu lado del cable, no para el nuestro.

Ejemplo completo

Una respuesta servida desde la copia guardada, con 18 segundos restantes antes de que expire:

200 OK

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

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