Stack Overflowで聞かれる為替レートAPIのトラブルシューティングに答える

統合が壊れると、開発者はエラーをそのままStack Overflowに貼り付ける。為替レートAPIについてはほぼ毎回同じ質問が出る——キーが拒否される、レート制限の壁にぶつかる、CORSエラーが出る、週末にレートが古く見える、といったものだ。ここでは、exchangerate.devを実例として直接的な解決策を示す。すべてのスニペットはhttps://api.exchangerate.devに対する実際の呼び出しである。

ベースURLはhttps://api.exchangerate.devである。最初の呼び出しはIPごとの上限付きで匿名でも動作するため、無料キーに登録する前にこれらのどれでも再現できる。

401 Unauthorized — キーが拒否される

キーはベアラートークンとしてAuthorizationヘッダーに設定し、末尾にスペースを伴うBearerという単語が必要である。キーにはexr_live_という接頭辞が付く。

curl https://api.exchangerate.dev/v1/latest/USD \
  -H "Authorization: Bearer exr_live_YOUR_KEY"

401のよくある原因: Bearer 接頭辞が抜けている、コピー&ペーストでキーに余分な改行や引用符が紛れ込んでいる、あるいはキーを保持する環境変数が読み込まれていない、のいずれかである。Authorizationを設定できないプラットフォームは、代わりにX-API-Keyヘッダーでキーを送信できる。

429 Too Many Requests — レート制限への対処

成功した従量対象レスポンスにはX-RateLimit-Remainingが含まれる。429にはRetry-Afterが返るため、その時間を待ってから再試行する。X-RateLimit-Scopeを見れば、毎分の上限、匿名アクセスの時間上限、月間クォータのどれを使い切ったかがわかる。無料プランは毎分12リクエスト、Basicは120、Proは500である。アカウントの残りクォータと月次リセットはGET /v1/accountで確認できる。

CORSエラー — ブラウザからAPIを呼び出す場合

CORSは匿名読み取りとAuthorization、X-API-Keyヘッダーを許可している。ただし、キー付きのブラウザリクエストは秘密にはならない。devtoolsを開けば誰でもexr_live_...をコピーできる。公開デモには匿名呼び出しを使い、アカウントのクォータを使う場合は自前のバックエンドを経由してキーをサーバー側に保持する。

// the key never reaches the browser
const r = await fetch("https://api.exchangerate.dev/v1/latest/USD", {
  headers: { Authorization: `Bearer ${process.env.EXCHANGERATE_API_KEY}` },
});
const data = await r.json();

為替レートを安全にキャッシュするには？

レートだけでなく、source、market_session、data_updated_atを含む成功した観測全体を保存する。活発なペアはサーバー側の60秒から始める。重複呼び出しは減るが、日次参照レート自体が新しくなるわけではない。

• ペアごとにHTTP呼び出しを作らず、複数通貨を1回のsymbolsリクエストにまとめる。
• 成功した2xxレスポンスだけを保存する。401、429、上流エラーをレートとして扱わない。
• 429ではRetry-AfterとX-RateLimit-Scopeを使い、固定の待ち時間を決め打ちしない。
• アカウントキーはサーバー側の設定に置き、公開ブラウザキャッシュやバンドルには入れない。

レートが古く見える、週末に変わらない

これは想定どおりの挙動であり、レスポンスがその理由を教えてくれる。活発に取引される通貨はライブで更新される(取引日に約60秒間隔)——現在のカバレッジは固定のマーケティング数値ではなくAPI自身が報告し、残りはECBおよびFREDによる日次参照レートを使う。週末はインターバンク市場が休場のためライブフィードが停止し、参照フィックスは最後に公表された値を保持する。2つのフィールドがこれを明示する:

レートを読むだけでなく金額を換算するには？

/v1/convert/{from}/{to}/{amount}を使う。レートと換算後の金額をまとめて返すため、手動で掛け算する必要はない:

curl https://api.exchangerate.dev/v1/convert/USD/EUR/100 \
  -H "Authorization: Bearer exr_live_YOUR_KEY"

過去データや時系列データを取得するには？

過去の特定の1日については、パスに日付を入れる: GET /v1/{YYYY-MM-DD}/{base}、1999年1月4日まで遡れる。1回の呼び出しである範囲全体の系列を取得するにはGET /v1/rangeをstart_dateとend_dateとともに使う。キーセット方式のページネーションを使っているため、一度に巨大な範囲をリクエストせず、カーソルをたどってほしい。

他のFX APIから移行中でエラーが出る場合

リクエストパラメータは一般的なFX APIの慣例(ベース通貨とsymbolsフィルター)に沿っているため、多くの移行はベースURLの差し替えだけで済み、コードの書き直しは不要である。レスポンスが異なる箇所では、このAPIはフィールドを削除するのではなく追加している(source、market_session、notice)——レスポンスを解析するコードが固定のキー集合を前提にしていないか確認してほしい。

動作する最短の呼び出し

キーも依存関係も不要:

curl https://api.exchangerate.dev/v1/latest/USD

レートとsource、market_sessionが返ってくるため、それぞれがどれだけ新しいかがわかる。無料キーを取得すれば上限が月10,000コールに引き上げられ、1分もかからない。