集成出错时,开发者会把报错粘到 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 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 会说明触发的是每分钟上限、匿名访问每小时上限,还是每月配额。Free 每分钟 10 个请求,Basic 60 个,Plus 120 个,Pro 300 个。剩余配额和重置时间见 GET /v1/account。
CORS 错误:从浏览器调用 API
CORS 允许匿名读取,也允许 Authorization 和 X-API-Key 请求头。但这不会让带密钥的浏览器请求保密:任何打开开发者工具的人都能复制 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 秒。这样能减少重复调用,但不会让每日参考汇率变得更新。
- 把多种货币合并到一个
symbols请求中,不要为每个货币对单独发起 HTTP 调用。 - 只缓存成功的 2xx 响应。不要把 401、429 或上游错误当作汇率保存。
- 收到 429 时使用
Retry-After和X-RateLimit-Scope,不要自行设定固定等待时间。 - 账户密钥只放在服务端配置中,绝不要放进公开的浏览器缓存或前端包。
汇率看起来没有变化,或周末不更新
这是预期行为,响应本身会告诉你原因。144种货币在交易日约每60秒更新。ECB为约30种货币提供每日备用值。周末银行间市场休市,实时推送暂停,每日参考定盘价沿用周五数据。以下两个字段对此有明确说明:
| 字段值 | 含义 | 更新时机 |
|---|---|---|
| source: live | 指示性即期汇率 | 盘中(约 60 秒),交易周内 |
| source: ecb_daily | 官方参考定盘价 | 每个交易日一次 |
| 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"如何获取历史或时间序列数据?
单日历史用 GET /v1/{YYYY-MM-DD}/{base}。Free 和无密钥历史限最近 30 天,Basic 为最近 1 年;Plus 和 Pro 凭密钥可追溯至 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,让你清楚每条数据的新鲜程度。申请免费密钥 可将限额提升至每月 5,000 次调用,注册只需一分钟。
汇率仅供参考、分析和展示,不是可执行报价,不得用于结算交易。Free 商业展示需显示来源链接,付费套餐无需标注。