错误处理

错误响应格式

请求失败时，API 会返回 HTTP 错误状态码以及包含 success: false 的 JSON 正文。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）：您的套餐不包含该端点或参数，例如 Free 套餐中的 /carat，或低于 Standard 套餐时的 XAU-BID。

校验错误

这些错误返回 HTTP 状态码 400，表示请求本身需要修正：

• 201 invalid_base：未知的 base 品种。
• 202 invalid_from 和 203 invalid_to：/convert 中的 from 或 to 品种未知。
• 204 invalid_amount：缺少 amount，或其不是数字。
• 205 invalid_date：日期格式错误，或日期在未来。
• 206 invalid_timeframe：缺少 start_date 或 end_date，或开始日期晚于结束日期。
• 207 timeframe_too_long：区间超出您套餐允许的范围（Free 为 30 天，付费套餐为 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" }));