Compresión y caché

Las lecturas públicas de gran tamaño, como GET /markets, ocupan megabytes de JSON. Solicite compresión y deje que el encabezado Cache-Control de cada respuesta le indique qué tan reciente es.

Compresión

Envíe Accept-Encoding: gzip y la API devolverá el cuerpo comprimido con gzip junto con Content-Encoding: gzip. GET /markets pasa de unos 4 MB a unos 0,6 MB.

• Los navegadores y fetch de Node.js envían el encabezado y descomprimen automáticamente.
• hypercall-client de Rust habilita gzip en su cliente HTTP, por lo que cada llamada REST lo solicita y lo decodifica de forma transparente.
• Python: requests y httpx envían el encabezado y descomprimen por defecto. urllib por sí solo no hace ninguna de las dos cosas, por lo que recibirá el cuerpo sin comprimir.
• curl necesita --compressed.

Las respuestas de menos de aproximadamente 1 KB se envían sin comprimir. Los frames de WebSocket no se ven afectados; consulte Compresión de WebSocket.

Cache-Control

Cada lectura le indica si una caché compartida puede conservarla.

Encabezado de respuesta	Dónde lo verá	Qué significa
public, max-age=N	Datos de mercado públicos: /markets, /instruments, /instrument-specs, /exchange-info, greeks, resúmenes de opciones y de vencimientos, theos históricos, lecturas de pools, /version	Cualquier caché puede reutilizar el cuerpo durante un máximo de N segundos. La mayoría están entre 1 y 15 segundos; los datos históricos pueden ser más largos.
public, max-age=N, stale-while-revalidate=M	Algunas de las lecturas anteriores	Transcurridos N segundos, una caché puede seguir sirviendo el cuerpo anterior durante hasta M segundos más mientras obtiene uno nuevo en segundo plano.
no-store	Lecturas autenticadas y asociadas a una wallet: portafolio, órdenes abiertas, fills, trades filtrados por wallet, configuración de MMP y similares	Ninguna caché las almacena. Cada solicitud llega a la API.
ninguno	Todo lo demás, incluido /orderbook y todas las escrituras	No se almacena en caché.

Considere que una lectura public puede tener hasta max-age segundos de antigüedad (más cualquier stale-while-revalidate). Cuando necesite el estado más reciente para una decisión de trading, léalo desde los canales de WebSocket o desde una lectura asociada a una wallet, que nunca se almacenan en caché.

Las respuestas de error (4xx, 5xx) nunca llevan public y nunca se almacenan en caché. Una caché no sigue sirviendo un cuerpo expirado mientras la API devuelve errores; usted recibe el error.

Solicitudes que siempre llegan a la API

Nunca se devuelve un cuerpo en caché a una solicitud que lleve cualquiera de estos elementos, y nada de lo que reciba dicha solicitud se almacena:

• Authorization o Cookie
• X-Hypercall-Signature o X-Hypercall-Expires-At-Ms (lecturas firmadas, como la configuración de MMP)
• X-Hypercall-Fence o X-Hypercall-Fence-Wait (consistencia de lectura tras escritura, consulte Market Maker Protection)
• X-Hypercall-Gateway-Token o X-Admin-Key
• cualquier método distinto de GET o HEAD, y los upgrades de WebSocket

Los fences de lectura tras escritura y la caché nunca se combinan. Una ruta que respeta X-Hypercall-Fence es no-store, y una ruta public nunca espera un fence.

X-Cache-Status

Las respuestas que pasan por la caché perimetral (edge cache) de Hypercall llevan X-Cache-Status:

Valor	Significado
HIT	Servida desde la caché perimetral, dentro de max-age.
MISS	Obtenida de la API. Si la respuesta era public, ahora está en caché.
BYPASS	La solicitud llevaba un encabezado de la lista anterior, por lo que fue directamente a la API y no se almacenó nada.
EXPIRED	La copia en caché había superado su vida útil, por lo que se volvió a consultar a la API.
STALE o UPDATING	Servida desde la caché dentro de la ventana de stale-while-revalidate mientras se obtiene una copia nueva.

Las escrituras y otras solicitudes que no son GET no llevan X-Cache-Status. El encabezado es informativo: no base la lógica de trading en él. No todos los entornos cuentan todavía con la caché perimetral. Una respuesta sin el encabezado proviene directamente de la API.