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당 분당 30회, 시간당 100회, 월 1,000회로 제한되므로, 간단한 테스트를 넘어서는 용도라면 인증을 하라.

"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이다. 금·은·구리 현물은 모든 요금제에서 제공된다. 새 요금제에는 선물이 없다. symbol을 생략하면 요금제에서 허용하는 기본 행을 반환한다.

"429 Too Many Requests" — 속도 제한 다루기

모든 응답에 X-RateLimit-Remaining이 실린다. 0이 되기 전에 읽고 속도를 늦춰라. 분당 요청 한도는 Free 10회, Basic 60회, Plus 120회, Pro 300회다. 짧은 캐시로 호출을 줄일 수 있다.

"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, 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은 최근 1년, Plus와 Pro는 전체 이력을 반환한다. 그러니 과거 데이터 조회가 예상보다 짧게 돌아온다면, 그것은 자신의 등급의 조회 범위이지 인증 오류가 아니다.

동작하는 가장 짧은 호출

키 없이, 올바른 심볼로:

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

신선도 플래그가 함께 담긴 15분 지연 금 가격이 돌아온다. 기여한 소스가 필요하면 ?include=sources를 붙여라. 전체 응답 구조와 더 높은 한도가 필요할 때는 무료 키 발급이 1분이면 끝난다. 언어별 안내를 원한다면, JavaScript로 실시간 금 가격 가져오기에서 REST 경로를 처음부터 끝까지 다루고, 금 가격 캐싱과 속도 제한 안에 머물기에서 대량 트래픽에서 그렇게 하는 방법을 다룬다.