Buenas prácticas

Ajusta la frecuencia de consulta a tu plan

Cada plan entrega los precios con un intervalo de actualización fijo: una vez al día en Free, cada 30 minutos en Lite, cada 10 minutos en Standard, cada 60 segundos en Advanced y Pro, cada 15 segundos en Ultra y Business, y cada 5 segundos en Enterprise. Solicitar /latest con más frecuencia devuelve los mismos precios y gasta cuota para nada.

Como regla general, guarda /latest en caché durante el intervalo de actualización de tu plan y guarda para siempre los datos de días pasados.

Solicita muchos símbolos a la vez

Una solicitud puede devolver cualquier número de símbolos y cuesta lo mismo que una solicitud de un solo símbolo. Pide todo lo que necesites en una sola llamada:

GET /api/v1/latest?api_key=YOUR_API_KEY&currencies=XAU,XAG,XPT,XPD,EUR,GBP

Consultar una vez cada 10 minutos consume unas 4500 solicitudes al mes, y consultar una vez por minuto, unas 45.000. Elige tu plan en consecuencia.

Usa una caché propia

Una pequeña caché delante de la API mantiene tu aplicación rápida y tu consumo predecible. También te permite seguir sirviendo los últimos precios válidos si una solicitud falla:

const TTL = 10 * 60 * 1000; // Plan Standard: actualizaciones cada 10 minutos
let cache = { at: 0, data: null };

export async function getPrices() {
  if (cache.data && Date.now() - cache.at < TTL) return cache.data;

  const res = await fetch("https://metalapi.com/api/v1/latest?currencies=XAU,XAG,XPT,XPD", {
    headers: { "X-API-Key": process.env.METALAPI_KEY },
  });
  const data = await res.json();

  if (!data.success) {
    if (cache.data) return cache.data; // sirve los últimos precios válidos
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

Usa el stream en lugar de consultar periódicamente

Para paneles y herramientas de trading que necesitan cada actualización, usa /stream en el plan Pro y superiores. Una única conexión Server-Sent Events de larga duración entrega los nuevos precios en cuanto llegan, sin ningún bucle de consultas que ajustar.

Para lógica de umbrales como “avísame cuando el oro supere los 4000 USD”, usa las alertas de precio y los webhooks y prescinde por completo de las consultas periódicas.

Gestiona los errores con elegancia

• Comprueba success en cada respuesta y basa tu lógica en error.code.
• Reintenta 104, 500 y 503 con backoff. No reintentes los errores de validación.
• Si no se puede acceder a la API, sigue mostrando el último precio válido junto con su marca de tiempo.
• Vigila la cabecera X-RateLimit-Remaining y la página de estado del sistema.

Encontrarás los detalles y el código en Manejo de errores.

Mantén segura tu integración

• Guarda las claves en variables de entorno o en un gestor de secretos, nunca en Git ni en bundles del lado del cliente.
• Usa claves restringidas por dominio para cualquier llamada desde el navegador.
• Usa una clave por aplicación y entorno, y rota las claves cuando alguien deje el equipo o una clave pueda haberse filtrado.
• Verifica la cabecera X-MetalAPI-Signature de cada webhook y rechaza las marcas de tiempo antiguas.

Consejos de rendimiento

• Reutiliza un único cliente HTTP para que las conexiones se mantengan abiertas entre solicitudes.
• Acepta respuestas comprimidas (gzip o br). La mayoría de los clientes HTTP lo hacen por defecto.
• Establece un tiempo de espera de unos 10 segundos por solicitud para que una red lenta nunca bloquee tu aplicación.
• Carga /symbols una vez al iniciar y valida con esa lista lo que introducen los usuarios, en lugar de dejar que los símbolos incorrectos hagan fallar las solicitudes.
• Llama a /usage desde tu sistema de monitorización para que te avise antes de quedarte sin cuota. Es gratuito.