Stack Overflow의 환율 API: 개발자 문제 해결 가이드

연동이 깨지면 개발자들은 오류를 Stack Overflow에 붙여넣습니다. 환율 API에서 나오는 질문은 거의 항상 같습니다: 거부된 키, 요청 한도 벽, CORS 오류, 주말에 멈춘 것처럼 보이는 환율입니다. exchangerate.dev를 예제로 삼아 바로 적용할 수 있는 해결책을 소개합니다. 모든 코드 조각은 https://api.exchangerate.dev에 대한 실제 호출입니다.

기본 URL은 https://api.exchangerate.dev입니다. 첫 호출은 IP당 한도가 있는 익명 상태로도 동작하므로, 무료 키를 발급받기 전에 아래 예제를 그대로 재현해 볼 수 있습니다.

401 Unauthorized — 키가 거부됨

키는 bearer 토큰 형태로 Authorization 헤더에 넣으며, 뒤에 공백이 붙은 Bearer라는 단어가 반드시 있어야 합니다. 키는 exr_live_ 접두사가 붙습니다.

curl https://api.exchangerate.dev/v1/latest/USD \
  -H "Authorization: Bearer exr_live_YOUR_KEY"

401의 흔한 원인은 다음과 같습니다: Bearer 접두사 누락, 복사-붙여넣기 과정에서 키에 섞여 들어간 줄바꿈이나 따옴표, 또는 키를 담은 환경 변수가 로드되지 않은 경우입니다. Authorization을 설정할 수 없는 플랫폼은 대신 X-API-Key 헤더로 키를 보낼 수 있습니다.

429 Too Many Requests — 요청 한도 처리하기

모든 응답에는 X-RateLimit-Remaining이 담겨 있습니다. 무작정 폴링하는 대신 이 값을 확인하고 0에 도달하기 전에 속도를 늦추세요. 무료 등급은 분당 12회, Basic은 120회, Pro는 500회입니다. 남은 할당량과 월간 초기화 시점은 언제든 GET /v1/account로 확인할 수 있습니다. 참조 환율은 매초 바뀌지 않으므로, 짧은 클라이언트 측 캐시만으로도 대개 한도 안에 여유 있게 머물 수 있습니다.

CORS 오류 — 브라우저에서 API 호출하기

키를 넣은 채로 프런트엔드 JavaScript에서 API를 직접 호출하지 마세요. 개발자 도구를 여는 누구에게나 exr_live_...가 노출되며, 브라우저는 이를 CORS로 차단합니다. 자체 백엔드를 거쳐 호출을 프록시하고, 키는 서버 측에만 두며, 브라우저는 자체 엔드포인트를 호출하게 하세요.

// the key never reaches the browser
const r = await fetch("https://api.exchangerate.dev/v1/latest/USD", {
  headers: { Authorization: `Bearer ${process.env.EXCHANGERATE_API_KEY}` },
});
const data = await r.json();

환율이 멈춘 것처럼 보이거나 주말에 바뀌지 않아요

이는 예상된 동작이며, 응답이 그 이유를 알려줍니다. 활발히 거래되는 통화는 거래일 기준 약 60초마다 실시간으로 가격이 갱신되며, 현재 커버리지는 고정된 마케팅 수치가 아니라 API가 직접 보고합니다. 나머지는 ECB와 FRED의 일일 참조 환율을 사용합니다. 주말에는 은행 간 시장이 휴장이므로 실시간 피드가 중단되고, 참조 고시가는 마지막으로 발표된 값을 그대로 유지합니다. 두 필드가 이를 명시적으로 보여줍니다:

환율만 읽는 게 아니라 금액을 변환하려면 어떻게 하나요?

/v1/convert/{from}/{to}/{amount}를 사용하세요. 환율과 변환된 금액을 함께 반환하므로 직접 곱셈할 필요가 없습니다:

curl https://api.exchangerate.dev/v1/convert/USD/EUR/100 \
  -H "Authorization: Bearer exr_live_YOUR_KEY"

과거 데이터나 시계열 데이터는 어떻게 가져오나요?

과거의 특정 하루라면 경로에 날짜를 넣으세요: GET /v1/{YYYY-MM-DD}/{base}, 1999-01-04까지 이력을 제공합니다. 한 번의 호출로 특정 기간 전체 시계열을 가져오려면 start_date와 end_date를 사용해 GET /v1/range를 호출하세요. 이 엔드포인트는 키셋 페이지네이션을 사용하므로, 거대한 범위를 한 번에 요청하지 말고 커서를 따라가세요.

Frankfurter에서 마이그레이션하다가 오류가 나나요?

요청 매개변수는 Frankfurter와 호환되므로, 대부분의 마이그레이션은 코드 재작성 없이 기본 URL만 바꾸면 됩니다. 응답이 다른 부분에서는 이 API가 필드를 제거하는 대신 (source, market_session, notice) 필드를 추가합니다. 정확한 매핑은 Frankfurter에서 마이그레이션하기 가이드를 참고하세요.

바로 동작하는 가장 짧은 호출

키도, 의존성도 필요 없습니다:

curl https://api.exchangerate.dev/v1/latest/USD

환율과 함께 source, market_session을 받아 각 값이 얼마나 신선한지 알 수 있습니다. 무료 키를 발급받으면 한도가 월 10,000회로 늘어나며, 1분이면 충분합니다.