exchangerate.dev연동이 깨지면 개발자들은 오류를 Stack Overflow에 붙여넣습니다. 환율 API에서 나오는 질문은 거의 항상 같습니다: 거부된 키, 요청 한도 벽, CORS 오류, 주말에 멈춘 것처럼 보이는 환율입니다. exchangerate.dev를 예제로 삼아 바로 적용할 수 있는 해결책을 소개합니다. 모든 코드 조각은 https://api.exchangerate.dev에 대한 실제 호출입니다.
- 401 오류는 거의 항상
Bearer접두사가 빠졌거나, 복사-붙여넣기 과정에서 키에 줄바꿈이 섞여 들어갔기 때문입니다. - 한도에 도달하기 전에
X-RateLimit-Remaining을 확인하세요. 429에서는X-RateLimit-Scope와Retry-After를 읽으세요. - 브라우저 익명 호출은 허용됩니다. 계정 키를 프런트엔드 JavaScript에 넣지 마세요.
- 모든 응답의
source와market_session이 환율이 왜 움직이지 않는지 정확히 알려줍니다.
기본 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를 보면 분당 한도, 익명 시간당 한도, 월간 할당량 중 무엇을 소진했는지 알 수 있습니다. 분당 Free 10회, Basic 60회, Plus 120회, Pro 300회입니다. 계정의 남은 할당량과 월간 초기화는 GET /v1/account로 확인하세요.
CORS 오류，브라우저에서 API 호출하기
CORS는 익명 읽기와 Authorization, X-API-Key 헤더를 허용합니다. 그렇다고 키를 넣은 브라우저 요청이 비공개가 되는 것은 아닙니다. 개발자 도구를 열면 누구나 exr_live_...를 복사할 수 있습니다. 공개 데모에는 익명 호출을 사용하고, 계정 할당량을 쓸 때는 자체 백엔드를 거쳐 키를 서버에 보관하세요.
// the key never reaches the browserconst 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를 사용하고 고정 대기 시간을 임의로 만들지 마세요. - 계정 키는 서버 설정에 보관하고 공개 브라우저 캐시나 번들에는 넣지 마세요.
환율이 멈춘 것처럼 보이거나 주말에 바뀌지 않아요
이는 예상된 동작이며, 응답이 그 이유를 알려줍니다. 144개 통화는 거래일에 약 60초마다 갱신됩니다. ECB는 약 30개 통화의 일일 대체값입니다. 주말에는 은행 간 시장이 휴장이므로 실시간 피드가 중단되고, 참조 고시가는 마지막으로 발표된 값을 그대로 유지합니다. 두 필드가 이를 명시적으로 보여줍니다:
| 필드 값 | 의미 | 갱신 시점 |
|---|---|---|
| source: live | 참고용 현물 시장 환율 | 장중 (~60초), 거래 주간 |
| source: ecb_daily | 공식 참조 고시가 | 영업일마다 1회 |
| source: market_daily | ECB 고시 없는 저장 종가 | 일일 시장 피드 |
| market_session: weekend | 은행 간 시장 휴장 | 실시간 피드 중단; 참조값은 금요일 값 유지 |
환율만 읽는 게 아니라 금액을 변환하려면 어떻게 하나요?
/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년부터는 Plus/Pro 키가 필요합니다. 한 번의 호출로 특정 기간 전체 시계열을 가져오려면 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을 받아 각 값이 얼마나 신선한지 알 수 있습니다. 무료 키를 발급받으면 한도가 월 5,000회로 늘어나며, 1분이면 충분합니다.
환율은 참조, 분석, 표시를 위해 발행됩니다. 딜링 견적이 아니며 거래 정산에 사용해서는 안 됩니다. Free는 눈에 보이는 출처 링크와 함께 상업적으로 표시할 수 있습니다. 유료는 출처 표시가 불필요합니다.