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를 맞는 대신, 이 값이 0에 가까워지기 전에 읽고 속도를 늦춰라. 무료 등급은 분당 30회 요청이고, Physical은 120회, Pro와 Realtime Pro는 500회다. 대부분의 앱에서는 가격이 실제로 움직이는 빈도에 맞춘 짧은 클라이언트 캐시만으로도 한도에서 충분히 멀리 떨어져 있을 수 있다. 현물 가격은 매초마다 의미 있게 바뀌지 않으므로, 몇 초짜리 캐싱이면 대개 충분하다.

"CORS error" — 브라우저에서 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 필요) — 업스트림마다 한 행씩, 각각 자체 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분이면 끝난다. 언어별 안내를 원한다면, JavaScript로 실시간 금 가격 가져오기에서 REST 경로를 처음부터 끝까지 다루고, 금 가격 캐싱과 속도 제한 안에 머물기에서 대량 트래픽에서 그렇게 하는 방법을 다룬다.