Лучшие практики

Согласуйте частоту опроса с тарифом

Каждый тариф отдаёт цены с фиксированным интервалом обновления: ежедневно на Free, каждые 30 минут на Lite, каждые 10 минут на Standard, каждые 60 секунд на Advanced и Pro, каждые 15 секунд на Ultra и Business и каждые 5 секунд на Enterprise. Если запрашивать /latest чаще, вы получите те же цены и потратите квоту впустую.

Простое правило: кешируйте /latest на время интервала обновления вашего тарифа, а данные за прошедшие дни — навсегда.

Запрашивайте много символов сразу

Один запрос может вернуть любое количество символов и стоит столько же, сколько запрос одного символа. Запрашивайте всё необходимое одним вызовом:

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

Опрос раз в 10 минут расходует около 4 500 запросов в месяц, а опрос раз в минуту — около 45 000. Выбирайте тариф с учётом этого.

Кешируйте на своей стороне

Небольшой кеш перед API ускоряет работу приложения и делает расход запросов предсказуемым. Кроме того, он позволяет и дальше отдавать последние корректные цены, если запрос завершился ошибкой:

const TTL = 10 * 60 * 1000; // тариф Standard: обновление каждые 10 минут
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; // отдаём последние корректные цены
    throw new Error(`${data.error.code}: ${data.error.info}`);
  }
  cache = { at: Date.now(), data };
  return data;
}

Поток вместо опроса

Для дашбордов и торговых инструментов, которым нужно каждое обновление, используйте /stream на тарифе Pro и выше. Одно долгоживущее подключение Server-Sent Events доставляет новые цены сразу после их появления — без цикла опроса, который приходится настраивать.

Для пороговой логики вроде «сообщить, когда золото пересечёт отметку 4 000 $» используйте ценовые оповещения и вебхуки и полностью откажитесь от опроса.

Корректно обрабатывайте ошибки

• Проверяйте success в каждом ответе и выбирайте дальнейшие действия по error.code.
• Повторяйте запросы при ошибках 104, 500 и 503 с нарастающей задержкой. Не повторяйте запросы с ошибками валидации.
• Если API недоступен, продолжайте показывать последнюю корректную цену вместе с её меткой времени.
• Следите за заголовком X-RateLimit-Remaining и страницей состояния системы.

Подробности и код — в руководстве Обработка ошибок.

Обеспечьте безопасность интеграции

• Храните ключи в переменных окружения или в менеджере секретов, но никогда — в Git или в клиентских бандлах.
• Для любых вызовов из браузера используйте ключи с ограничением по доменам.
• Используйте отдельный ключ для каждого приложения и окружения и меняйте ключи, когда кто-то уходит из команды или ключ мог утечь.
• Проверяйте заголовок X-MetalAPI-Signature каждого вебхука и отклоняйте устаревшие метки времени.

Советы по производительности

• Используйте один экземпляр HTTP-клиента, чтобы соединения между запросами оставались открытыми.
• Принимайте сжатые ответы (gzip или br). Большинство HTTP-клиентов делают это по умолчанию.
• Установите тайм-аут запроса около 10 секунд, чтобы медленная сеть не блокировала приложение.
• Загружайте /symbols один раз при запуске и проверяйте по этому списку пользовательский ввод, чтобы неверные символы не приводили к неудачным запросам.
• Вызывайте /usage из системы мониторинга, чтобы заранее получать предупреждение о скором исчерпании квоты. Это бесплатно.