エラーハンドリング

エラーレスポンスの形式

リクエストが失敗すると、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"
  }
}

分岐には、変更される可能性のあるinfoのテキストではなく、codeまたはtypeを使ってください。コードは以前のバージョンの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）：1分あたりの上限に達しました。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では、有効なシンボルが1つ以上あれば、不明なシンボルはスキップされます。

その他のエラー

• 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秒）でリトライし、3回リトライしても失敗した場合はあきらめます。
• それ以外（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" }));