Stack Overflow 上的汇率 API：开发者常见报错，逐一解答

集成出错时，开发者会把报错粘到 Stack Overflow。对于汇率 API，问题几乎总是那几类：密钥被拒、触达限流上限、CORS 错误，或者周末汇率看起来没有变化。以下是直接的解决方案，以 exchangerate.dev 为实例。每段代码片段都是针对 https://api.exchangerate.dev 的真实调用。

基础 URL 为 https://api.exchangerate.dev。首次调用可匿名进行（按 IP 限速），因此你可以在注册免费密钥之前重现以下任意示例。

401 Unauthorized——密钥被拒

密钥需放入 Authorization 请求头，以 Bearer Token 形式传递，且必须有 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 个请求，基础版 120 个，专业版 500 个。账户的剩余配额和每月重置时间可通过 GET /v1/account 查看。

CORS 错误——从浏览器调用 API

CORS 允许匿名读取，也允许 Authorization 和 X-API-Key 请求头。但这不会让带密钥的浏览器请求保密：任何打开开发者工具的人都能复制 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 秒。这样能减少重复调用，但不会让每日参考汇率变得更新。

• 把多种货币合并到一个 symbols 请求中，不要为每个货币对单独发起 HTTP 调用。
• 只缓存成功的 2xx 响应。不要把 401、429 或上游错误当作汇率保存。
• 收到 429 时使用 Retry-After 和 X-RateLimit-Scope，不要自行设定固定等待时间。
• 账户密钥只放在服务端配置中，绝不要放进公开的浏览器缓存或前端包。

汇率看起来没有变化，或周末不更新

这是预期行为，响应本身会告诉你原因。交易活跃的货币会实时刷新（交易日约每 60 秒更新一次）；当前覆盖范围由 API 直接报告，而不是固定的宣传数字，其余货币使用 ECB 和 FRED 的每日参考汇率。周末银行间市场休市，实时推送暂停，每日参考定盘价沿用周五数据。以下两个字段对此有明确说明：

如何换算金额，而不只是读取汇率？

使用 /v1/convert/{from}/{to}/{amount}。它会同时返回汇率和换算后的金额，无需手动相乘：

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

如何获取历史或时间序列数据？

查询某个历史日期，只需在路径中指定日期：GET /v1/{YYYY-MM-DD}/{base}，历史数据最早可追溯至 1999-01-04。如需一次性获取某个日期范围的完整序列，使用 GET /v1/range 并传入 start_date 和 end_date；该接口采用键集分页，请跟随游标翻页，不要一次请求过大的时间范围。

从其他外汇 API 迁移时遇到报错？

请求参数遵循常见的外汇 API 惯例（基础货币加上 symbols 过滤参数），因此大多数迁移只需更换基础 URL，无需重写代码。响应格式的差异在于，本 API 会新增字段（source、market_session、notice）而非删除字段——如果你的响应解析代码假设了固定的字段集合，请检查一下。

最简单的可用调用

无需密钥，无需依赖：

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

你将获得汇率数据，以及 source 和 market_session，让你清楚每条数据的新鲜程度。申请免费密钥 可将限额提升至每月 10,000 次调用，注册只需一分钟。