Обработка ошибок

Формат ответа с ошибкой

Если запрос завершается неудачей, API отвечает HTTP-статусом ошибки и телом JSON с success: false. Объект error содержит числовой code, машиночитаемый type и понятное человеку сообщение info:

{
  "success": false,
  "error": {
    "code": 101,
    "type": "no_api_key",
    "info": "User did not supply an API Key"
  }
}

Ориентируйтесь на code или type, а не на текст info, который может меняться. Коды совпадают с кодами прежних версий MetalAPI, поэтому существующие интеграции продолжают работать.

Ошибки аутентификации и аккаунта

• 101 no_api_key (401): в запросе нет ключа API.
• 102 invalid_api_key (401): ключ неизвестен или отозван.
• 103 account_inactive (403): аккаунт неактивен. Обратитесь в поддержку.
• 107 origin_not_allowed (403): ключ с ограничением по доменам использован на сайте, которого нет в списке разрешённых.

Ошибки лимитов и тарифа

• 104 too_many_requests (429): достигнут поминутный лимит. Подождите столько секунд, сколько указано в заголовке Retry-After.
• 105 quota_exceeded (429): месячная квота исчерпана до 1-го числа следующего месяца (UTC).
• 106 plan_restriction (403): эндпоинт или параметр не входит в ваш тариф, например /carat на Free или XAU-BID на тарифах ниже Standard.

Ошибки валидации

Эти ошибки возвращаются с HTTP-статусом 400 и означают, что нужно исправить сам запрос:

• 201 invalid_base: неизвестный символ base.
• 202 invalid_from и 203 invalid_to: неизвестный символ from или to в /convert.
• 204 invalid_amount: amount не указан или не является числом.
• 205 invalid_date: дата в неверном формате или дата в будущем.
• 206 invalid_timeframe: не указан start_date или end_date либо начало периода позже его конца.
• 207 timeframe_too_long: период длиннее, чем допускает ваш тариф (30 дней на Free, 365 на платных тарифах).
• 208 invalid_symbols: ни один из запрошенных символов не существует.
• 209 invalid_unit: неподдерживаемое значение unit.
• 210 invalid_carat: неподдерживаемое значение каратов.

Неизвестные символы в currencies пропускаются, если хотя бы один символ корректен.

Другие ошибки

• 300 no_results (404): запрос корректен, но данных нет — например, для даты раньше начала истории символа.
• 404 invalid_function (404): неизвестный эндпоинт. Проверьте URL.
• 500 server_error (500): непредвиденная ошибка на нашей стороне.
• 503 service_unavailable (503): данные о ценах временно недоступны.

Обработка ошибок в коде

Проверяйте success в каждом ответе и превращайте сбои в ошибки, которые ваш код может проанализировать. Эта вспомогательная функция также справляется с ответами не в формате JSON от прокси-серверов:

async function metalapi(path, params = {}) {
  const url = new URL(`https://metalapi.com/api/v1/${path}`);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);

  const res = await fetch(url, { headers: { "X-API-Key": process.env.METALAPI_KEY } });
  const data = await res.json().catch(() => ({
    success: false,
    error: { code: res.status, type: "http_error", info: res.statusText },
  }));

  if (!data.success) {
    const err = new Error(`MetalAPI ${data.error.code} (${data.error.type}): ${data.error.info}`);
    err.code = data.error.code;
    err.retryAfter = Number(res.headers.get("Retry-After")) || undefined;
    throw err;
  }
  return data;
}

Стратегия повторных попыток

Повторяйте только те запросы, которые могут завершиться успешно со второй попытки:

• 104: подождите Retry-After секунд и повторите запрос.
• 500, 503 и сетевые ошибки: повторяйте с экспоненциальной задержкой (1 с, 2 с, 4 с) и прекращайте после трёх повторов.
• Всё остальное (с 101 по 103, с 105 по 107, коды валидации 2xx, 300, 404): не повторяйте. Вместо этого исправьте запрос, ключ или тариф.

Повтор запросов с ошибками 104 и 5xx ничего не стоит, потому что такие неудачные запросы не тарифицируются.

async function withRetry(fn, retries = 3) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err.code === undefined || err.code === 104 || err.code >= 500;
      if (!retryable || attempt >= retries) throw err;
      const delay = err.retryAfter ? err.retryAfter * 1000 : 1000 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

const data = await withRetry(() => metalapi("latest", { currencies: "XAU,XAG" }));