Stack Overflow上の金価格API:開発者のトラブルシューティングに答える

連携がうまくいかなくなると、開発者はそのエラーをStack Overflowに貼り付ける。金価格APIについて出てくる質問は、ほぼ毎回同じ一握りに絞られる。認証拒否、不正な形式のシンボル、レート制限の壁、あるいはブラウザからのCORSエラーだ。本稿ではgoldprice.devを実例として、それぞれを直接解決していく。以下のコード片はすべてhttps://api.goldprice.devに対する、実際に動く呼び出しだ。

"401 Unauthorized" — APIキーが拒否される

キーはベアラートークンとして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-FUTURESだ。先物にはFUTURESという契約種別を使う。例えばXAU-USD-FUTURESのように。ただし金先物にはBasicプラン、銀と銅にはProプランが必要な点に注意してほしい。無料プランでこれらのシンボルを指定すると403 plan_gatedが返る。symbolを完全に省略すると、自分のプランで許可されているデフォルトの行が返ってくるので、これもエラーを避ける有効な方法だ。

"429 Too Many Requests" — レート制限への対処

すべてのレスポンスにX-RateLimit-Remainingヘッダーが付いている。ゼロに達する前にそれを読み取って自ら速度を落とすべきであり、闇雲にポーリングして429を食らうべきではない。無料プランは毎分30リクエスト、Physicalは120、ProとRealtime Proは500だ。ほとんどのアプリでは、価格が実際に動く頻度に合わせた短いクライアント側キャッシュを挟むだけで、制限には十分余裕を持って収まる。現物価格は毎秒有意に変化するわけではないので、数秒間キャッシュするのが通常は適切だ。

"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、bid、ask、computed_at、is_staleのみを返す。それ以外はない。より豊富な情報はすべて?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使用時)— アップストリームごとに1行、それぞれ独自のpriceとtimestampを持つ。データソース間で食い違いがある場合、divergence_bps(?include=stats使用時)がその乖離幅を教えてくれるので、出所不明な単一の混合値を鵜呑みにするのではなく、自分で許容範囲を設定できる。

"過去データ/OHLCデータはどう取得するか?"

日次終値の履歴はGET /v1/prices/historyで取得でき、すべてのプランで利用できる。変わるのは、どこまで遡れるかだ。無料プランは直近30日分、Basicは直近1年分、Proは全履歴を返す。したがって、履歴クエリの結果が想定より短い場合、それは自分のプランのウィンドウ制限によるものであり、認証エラーではない。

動く最短の呼び出し

キー不要、正しいシンボルを指定するだけ。

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

これで、陳旧度フラグ付きの、リアルタイムで偽りのない金価格が返ってくる。寄与しているデータソースが欲しければ?include=sourcesを加える。完全なレスポンス形式とより高い上限が欲しくなったら、無料キーの取得は1分で終わる。特定言語向けの手順を見たいなら、Fetch live gold prices in JavaScriptがREST経路を端から端まで解説しており、Caching gold prices and staying inside rate limitsは大量アクセス時の扱い方をカバーしている。