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 限制每分钟 30 次、每小时 100 次、每月 1,000 次请求。因此，超出快速测试范围后，请务必进行鉴权。

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

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

# 错误，400 invalid_symbolcurl "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。所有套餐都提供黄金、白银和铜现货。新套餐不包含期货。省略 symbol 会返回当前套餐允许的默认数据行。

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

每个响应都带有 X-RateLimit-Remaining。在归零前读取并降速。每分钟上限为 Free 10 次、Basic 60 次、Plus 120 次、Pro 300 次。短期缓存可减少调用。

"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();

如果目标只是展示实时价格而不是处理 JSON 数据，可以使用免费黄金价格小组件。它的托管 iframe 无需 API 密钥，且完全避开了浏览器 CORS 的问题。

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

默认响应包含 price、computed_at 和 is_stale。bid/ask 为付费专属可选字段，只有一致的双边报价可用时才出现。 更丰富的数据都要通过 ?include= 按需获取：?include=sources 增加 sources[] 数组，?include=karat 增加按成色分克重的换算明细，?include=stats（仅限鉴权）增加 open_price、high_price、low_price、prev_close_price、涨跌幅字段，以及 divergence_bps / divergence_flag。?include=all 会返回你的鉴权级别所允许的全部内容。有两个字段对准确性至关重要：

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

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

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

最简单的可用调用

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

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

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