Caché

Algunos endpoints sirven su respuesta desde un caché interno para que las llamadas repetidas no paguen el costo de regenerar un payload idéntico. Dos headers de respuesta describen lo que pasó en tu llamada específica: X-Cache y X-Cache-TTL.

Por qué importa

Un cliente que consulta el estado de una campaña alcanza fácilmente decenas de miles de peticiones por minuto. Cuando cada uno de esos clientes recibe la misma respuesta durante un intervalo corto, cachear ese resultado es la diferencia entre una integración que escala y una que se autolimita. El par de headers que se describe abajo permite que tu cliente vea explícitamente el estado del caché, para evitar las peticiones que no necesitas y razonar sobre qué tan fresca está la información.

Los dos headers

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

Header	Significado
`X-Cache`	Uno de `HIT`, `MISS` o `BYPASS`. Describe cómo se produjo la respuesta.
`X-Cache-TTL`	Segundos restantes antes de que la entrada cacheada actual expire y la siguiente llamada provoque un refresco. Hasta ese momento, cada cliente recibe el mismo payload.

Valores de X-Cache

✓

HIT: la respuesta se sirvió íntegramente desde el caché. X-Cache-TTL indica cuántos segundos seguirá vigente la entrada antes de expirar. Algunos endpoints de catálogo mantienen entradas permanentes y emiten HIT sin TTL: esas fotos permanecen válidas indefinidamente desde tu perspectiva.

MISS: no había una entrada utilizable en caché, así que la respuesta se generó al momento y se almacenó para los siguientes clientes. X-Cache-TTL indica la vida útil de la entrada que se acaba de escribir.

○

BYPASS: este endpoint no cachea sus respuestas. Cada llamada se computa en tiempo real, típicamente porque el payload depende de estado por-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 entrada cacheada es `MISS`; las siguientes dentro de la misma ventana son `HIT`.
`GET /api/v6/tools/countries`	`HIT`	-	El catálogo es una entrada permanente en caché. Sin TTL header.
`GET /api/v6/tools/countries/{code}`	`HIT`	-	Igual que el listado.

Las respuestas de error (401, 404, 429, 5xx) siempre llevan X-Cache: BYPASS, independientemente del endpoint que se estaba llamando.

Patrones recomendados para el cliente

Evita las peticiones que no necesitas. Cuando X-Cache: HIT viene acompañado de X-Cache-TTL: N, los próximos N segundos devolverán el mismo payload. Agenda tu siguiente llamada para ahora + N segundos (suma un pequeño jitter aleatorio para que múltiples clientes no se sincronicen en el instante del refresco).
Lleva el estado del caché a tu observabilidad. Registra X-Cache junto al request id. Un cambio sostenido hacia MISS suele ser la señal más temprana de un cambio en el comportamiento de caché, mucho antes de que se mueva la latencia de cola.
Calibra tus expectativas de SLA. Un HIT refleja el estado del mundo en el momento en que se escribió la entrada. Para dashboards y vistas de estado normalmente está bien; para confirmar eventos que requieren inmediatez (como la llegada de un OTP), usa un webhook en lugar de polling.

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

Ejemplo del wire

Una respuesta servida desde caché, con 18 segundos restantes antes de que expire la entrada:

200 OK

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

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