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이 담깁니다. 429는 Retry-After를 반환하므로 지정된 시간만큼 기다린 뒤 재시도하세요. X-RateLimit-Scope를 보면 분당 한도, 익명 시간당 한도, 월간 할당량 중 무엇을 소진했는지 알 수 있습니다. 무료 등급은 분당 12회, Basic은 120회, Pro는 500회입니다. 계정의 남은 할당량과 월간 초기화 시점은 GET /v1/account로 확인할 수 있습니다.

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

CORS는 익명 읽기와 Authorization, X-API-Key 헤더를 허용합니다. 그렇다고 키를 넣은 브라우저 요청이 비공개가 되는 것은 아닙니다. 개발자 도구를 열면 누구나 exr_live_...를 복사할 수 있습니다. 공개 데모에는 익명 호출을 사용하고, 계정 할당량을 쓸 때는 자체 백엔드를 거쳐 키를 서버에 보관하세요.

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

환율을 안전하게 캐시하려면 어떻게 하나요?

환율뿐 아니라 source, market_session, data_updated_at을 포함한 성공한 관측값 전체를 저장하세요. 활발한 통화쌍은 서버에서 60초 캐시로 시작하세요. 중복 호출은 줄지만 일일 참조 환율 자체가 더 최신이 되는 것은 아닙니다.

• 통화쌍마다 HTTP 호출을 만들지 말고 여러 통화를 하나의 symbols 요청으로 묶으세요.
• 성공한 2xx 응답만 캐시하세요. 401, 429, 상위 공급자 오류를 환율처럼 저장하지 마세요.
• 429에서는 Retry-After와 X-RateLimit-Scope를 사용하고 고정 대기 시간을 임의로 만들지 마세요.
• 계정 키는 서버 설정에 보관하고 공개 브라우저 캐시나 번들에는 넣지 마세요.

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

이는 예상된 동작이며, 응답이 그 이유를 알려줍니다. 활발히 거래되는 통화는 거래일 기준 약 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를 호출하세요. 이 엔드포인트는 키셋 페이지네이션을 사용하므로, 거대한 범위를 한 번에 요청하지 말고 커서를 따라가세요.

다른 FX API에서 마이그레이션하다가 오류가 나나요?

요청 매개변수는 FX API에서 흔히 쓰이는 방식(기준 통화에 symbols 필터를 더하는 구조)을 따르므로, 대부분의 마이그레이션은 코드 재작성 없이 기본 URL만 바꾸면 됩니다. 응답이 다른 부분에서는 이 API가 필드를 제거하는 대신 (source, market_session, notice) 필드를 추가합니다 — 응답을 파싱하는 코드가 고정된 키 집합을 가정하고 있지 않은지 확인하세요.

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

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

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

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