exchangerate.dev統合が壊れると、開発者はエラーをそのままStack Overflowに貼り付ける。為替レートAPIについてはほぼ毎回同じ質問が出る：キーが拒否される、レート制限の壁にぶつかる、CORSエラーが出る、週末にレートが古く見える、といったものだ。ここでは、exchangerate.devを実例として直接的な解決策を示す。すべてのスニペットはhttps://api.exchangerate.devに対する実際の呼び出しである。
- 401はほぼ常に
Bearer接頭辞の欠落か、コピー&ペーストで紛れ込んだ改行を含むキーが原因である。 - 上限に達する前に
X-RateLimit-Remainingを追跡する。429ではX-RateLimit-ScopeとRetry-Afterを確認する。 - ブラウザからの匿名呼び出しは許可されている。アカウントキーをフロントエンドのJavaScriptに置いてはならない。
- すべてのレスポンスにある
sourceとmarket_sessionが、レートが動いていない正確な理由を教えてくれる。
ベース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を見れば、毎分の上限、匿名アクセスの時間上限、月間クォータのどれを使い切ったかがわかる。毎分: Free 10、Basic 60、Plus 120、Pro 300。残りクォータと月次リセットはGET /v1/accountで確認できる。
CORSエラー、ブラウザからAPIを呼び出す場合
CORSは匿名読み取りとAuthorization、X-API-Keyヘッダーを許可している。ただし、キー付きのブラウザリクエストは秘密にはならない。devtoolsを開けば誰でもexr_live_...をコピーできる。公開デモには匿名呼び出しを使い、アカウントのクォータを使う場合は自前のバックエンドを経由してキーをサーバー側に保持する。
// the key never reaches the browserconst 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を使い、固定の待ち時間を決め打ちしない。 - アカウントキーはサーバー側の設定に置き、公開ブラウザキャッシュやバンドルには入れない。
レートが古く見える、週末に変わらない
これは想定どおりの挙動であり、レスポンスがその理由を教えてくれる。全144通貨は取引日に約60秒ごとに更新される。約30通貨はECBを日次代替値に使う。週末はインターバンク市場が休場のためライブフィードが停止し、参照フィックスは最後に公表された値を保持する。2つのフィールドがこれを明示する:
| フィールド値 | 意味 | 動くタイミング |
|---|---|---|
| source: live | 参考用のスポット市場レート | 取引週の日中(約60秒間隔) |
| source: ecb_daily | 公式な参照フィックス | 営業日に1回 |
| source: market_daily | ECB対象外の保存終値 | 日次市場データ |
| market_session: weekend | インターバンク市場が休場 | ライブフィードは停止し、参照値は金曜の値を維持 |
レートを読むだけでなく金額を換算するには？
/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年からはPlus/Proのキーが必要。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が返ってくるため、それぞれがどれだけ新しいかがわかる。無料キーを取得すれば上限が月5,000コールに引き上げられ、1分もかからない。
レートは参照・分析・表示用に公開されている。ディーリングクオートではなく、取引の決済に使用すべきではない。Freeは目立つクレジットリンク付きで商用表示できる。有料プランはクレジット不要。