Stack Overflow 上关于黄金价格 API 的开发者报错，逐一解答

每当集成出现问题，开发者就会把报错粘贴到 Stack Overflow 上。关于黄金价格 API 出现的问题，几乎总是那几类：鉴权被拒、符号格式错误、触发速率限制，或者浏览器 CORS 报错。本文直接解决每一个问题，以 goldprice.dev 作为实际示例。下面的每段代码都是针对 https://api.goldprice.dev 的真实可运行调用。

"401 Unauthorized" — 我的 API 密钥被拒绝

密钥需要以 Bearer Token 的形式放入 Authorization 请求头，且 Bearer（后跟一个空格）必须存在：

curl https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT \
  -H "Authorization: Bearer ga_live_YOUR_KEY"

真正导致 401 的三种情况：缺少 Bearer 前缀、复制粘贴时密钥里混入了多余的换行符或引号，或者密钥从一个未加载的环境变量中读取。密钥以 ga_live_ 为前缀。开始时不一定需要密钥——匿名调用可以工作，但每个 IP 每小时限制 100 次请求，且返回精简版响应结构。因此，超出快速测试范围后，请务必进行鉴权。

"400 invalid_symbol" — 最常见的初始错误

symbol 参数不是单纯的金属代码，而是 BASE-QUOTE-CONTRACT。传入 symbol=XAU 会返回 400 invalid_symbol；黄金实时现货的正确值是 XAU-USD-SPOT：

# 错误 — 400 invalid_symbol
curl "https://api.goldprice.dev/v1/prices?symbol=XAU"

# 正确
curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

白银现货是 XAG-USD-SPOT，铜是 HG-USD-SPOT。期货使用 FUTURES 合约类型，例如 XAU-USD-FUTURES——注意黄金期货需要 Basic 套餐，白银和铜需要 Pro 套餐，因此在免费套餐上这些代码会返回 403 plan_gated。完全省略 symbol 参数会返回你当前套餐允许的默认数据行，这也是避免该报错的一种有效方式。

"429 Too Many Requests" — 处理速率限制

每个响应都带有 X-RateLimit-Remaining 请求头。在触零之前读取它并主动降速，而不是盲目轮询直到遇到 429。免费套餐是每分钟 30 次请求；Basic 是 120 次；Pro 和 Realtime 是 500 次。对于大多数应用，一个短期的客户端缓存——TTL 与价格实际变动频率相匹配——就足以让你轻松保持在限额以内。现货价格不会每秒都发生有意义的变化，所以缓存几秒钟通常是合理的。

"CORS 报错" — 从浏览器调用 API

不要在前端 JavaScript 中直接用你的密钥调用 API。原因有两个：一是任何人打开开发者工具就能看到 ga_live_...，二是浏览器 CORS 策略会阻止该请求。正确做法是通过你自己的后端代理该调用，将密钥保存在服务端，让浏览器请求你自己的接口：

// 你的后端路由 — 密钥永远不会到达浏览器
const r = await fetch(
  "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT",
  { headers: { Authorization: `Bearer ${process.env.GOLDPRICE_API_KEY}` } },
);
const data = await r.json();

"哪个字段才是价格？" — 读取响应结构

匿名响应包含 price、bid、ask、computed_at、is_stale、sources[] 数组，以及按成色分克重的换算明细。通过鉴权后，响应结构还会增加 open_price、high_price、low_price、prev_close_price、涨跌幅字段，以及 divergence_bps / divergence_flag。有两个字段对准确性至关重要：

• is_stale — 当数值超出其预期刷新窗口时为 true。在展示价格之前务必检查此字段。
• sources[] — 每行对应一个上游数据源，各自有独立的 price 和 timestamp。当数据源出现分歧时，divergence_bps 会告诉你偏差幅度，让你可以设定自己的容忍阈值，而不是盲目相信一个混合后的数字。

"如何获取历史 / OHLC 数据？"

每日收盘历史数据通过 GET /v1/prices/history 获取，所有套餐均可用——区别在于能回溯多久。免费套餐返回最近 30 天，Basic 返回最近一年，Pro 返回完整历史。所以如果历史查询返回的数据比预期少，那是你套餐的时间窗口限制，而非鉴权错误。

最简单的可用调用

无需密钥，使用正确的符号：

curl "https://api.goldprice.dev/v1/prices?symbol=XAU-USD-SPOT"

这将返回一个带有数据来源和陈旧标志的实时真实黄金价格。当你需要完整的响应结构和更高的限额时，申请一个免费密钥只需一分钟。如果你希望查看特定语言的使用说明，Fetch live gold prices in JavaScript 完整覆盖了 REST 调用的全流程，Caching gold prices and staying inside rate limits 则介绍了如何在大规模场景下使用。