指南指南

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

开发者在 Stack Overflow 上遇到的外汇 API 报错,逐一解决:401 认证错误、429 限流、浏览器端 CORS 错误、周末汇率不更新、如何换算金额,以及如何获取历史或时间序列数据。

2026年8月6日 · 6 分钟阅读

集成出错时,开发者会把报错粘到 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 · authenticated
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_...。公开演示可使用匿名调用;要使用账户配额,请通过自己的后端转发,并将密钥留在服务端。

javascript · your backend route
// 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 · convert 100 USD to EUR
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 · no key
curl https://api.exchangerate.dev/v1/latest/USD

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

指示性数据,不用于结算

汇率仅供参考、分析和展示,不是可执行报价,不得用于结算交易。Free 商业展示需显示来源链接,付费套餐无需标注。

常见问题

为什么汇率 API 返回 401 错误?

401 几乎总是因为 Authorization 请求头格式不正确。应以 "Bearer exr_live_..." 的形式传递密钥,确保有 Bearer 前缀和空格,并检查是否因复制粘贴带入了多余的换行符或引号。对于无法设置 Authorization 头的平台,可改用 X-API-Key 请求头。

如何处理 429 限流错误?

等待 Retry-After 指定的时间后再重试,并通过 X-RateLimit-Scope 判断触发了哪项上限。X-RateLimit-Remaining 可帮助你在归零前降速。通过 GET /v1/account 查看账户配额,并且只缓存成功响应。

如何缓存汇率而不提供容易误解的旧数据?

缓存完整的成功观测值,把 source、market_session 和 data_updated_at 与汇率一起保存。对实时货币对,60 秒服务端缓存可作为减少重复调用的起点,但不会让每日参考汇率变得更新。不要把 401、429 或上游错误当作有效汇率缓存。

为什么周末汇率不更新?

周末银行间市场休市,实时推送暂停,每日参考定盘价沿用周五数据。响应会直接告诉你:market_session 将显示为 "weekend",source 将是每日参考类别而非 "live"。

如何获取历史汇率?

查询单日历史,请求 /v1/{YYYY-MM-DD}/{base}(历史数据最早追溯至 1999-01-04)。如需在一次调用中获取日期范围数据,使用 /v1/range 并传入 start_date 和 end_date,跟随键集分页游标翻页。

继续阅读

从免费API密钥开始

免费套餐每月提供5,000次请求。无需信用卡。

获取免费密钥