When an integration breaks, developers paste the error into Stack Overflow. For an exchange rate API the questions are almost always the same: a rejected key, a rate-limit wall, a CORS error, or a rate that looks stale over the weekend. Here are direct fixes, using exchangerate.dev as the worked example. Every snippet is a real call against https://api.exchangerate.dev.
- A 401 almost always means a missing
Bearerprefix or a key with a stray newline from copy-paste. - Track
X-RateLimit-Remainingbefore the limit. On a 429, readX-RateLimit-ScopeandRetry-After. - Anonymous browser calls are allowed. Never put an account key in front-end JavaScript.
sourceandmarket_sessionon every response tell you exactly why a rate is not moving.
The base URL is https://api.exchangerate.dev. Latest rates work anonymously, capped per IP. Keyless history covers 30 days; older dates need a paid key.
401 Unauthorized, the key is rejected
The key goes in the Authorization header as a bearer token, and the word Bearer with a trailing space has to be present. Keys are prefixed exr_live_.
curl https://api.exchangerate.dev/v1/latest/USD \ -H "Authorization: Bearer exr_live_YOUR_KEY"The usual causes of a 401: the Bearer prefix is missing, the key picked up a stray newline or quote from a copy-paste, or the env var holding it is not loaded. Platforms that cannot set Authorization can send the key as an X-API-Key header instead.
429 Too Many Requests, handling rate limits
Successful metered responses carry X-RateLimit-Remaining. A 429 supplies Retry-After; respect that value instead of assuming every limit resets after 60 seconds. Read X-RateLimit-Scope to see whether you hit the minute limit, anonymous hourly cap, or monthly quota. Free allows 10 requests a minute, Basic 60, Plus 120, and Pro 300.
CORS error, calling the API from the browser
CORS permits anonymous reads and the Authorization and X-API-Key headers. That does not make a keyed browser request private: anyone who opens devtools can copy exr_live_.... Anonymous calls are fine for evaluation. For an account-attributed production call, proxy through your backend and keep the key server-side.
// 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();How should I cache exchange rates safely?
Cache a complete successful observation: rate, source, market_session, and data_updated_at. For all pairs, start with 60 seconds on the server. That cuts duplicate calls. It does not make a daily reference rate fresher, so keep the observation fields beside the number.
- Batch currencies into one
symbolsrequest instead of caching one HTTP call per pair. - Cache successful 2xx responses. Do not store a 401, 429, or upstream error as though it were a rate.
- On 429, use
Retry-AfterandX-RateLimit-Scope; do not invent a fixed retry delay. - Keep account keys in server-side configuration, never in a public browser cache or bundle.
The rate looks stale or will not change on weekends
This is expected, and the response tells you why. All 144 currencies reprice live (~60s on trading days); ECB fixes provide daily fallback for about 30 currencies. Over a weekend the interbank market is closed, so the live feed pauses and reference fixes carry their last published value. Two fields make this explicit:
| Field value | What it means | When it moves |
|---|---|---|
| source: live | Indicative spot rate | Intraday (~60s), trading week |
| source: ecb_daily | Official reference fix | Once per business day |
| source: market_daily | Stored close, no ECB fix | Daily market feed |
| market_session: weekend | Interbank market closed | Live feed paused; reference carries Friday |
How do I convert an amount, not just read a rate?
Use /v1/convert/{from}/{to}/{amount}. It returns the rate and the converted amount together, so you do not multiply by hand:
curl https://api.exchangerate.dev/v1/convert/USD/EUR/100 \ -H "Authorization: Bearer exr_live_YOUR_KEY"How do I get historical or time-series data?
Use GET /v1/{YYYY-MM-DD}/{base} for one day; Plus and Pro reach 1999-01-04. For a full series across a range in one call, use GET /v1/range with start_date and end_date; it uses keyset pagination, so follow the cursor rather than requesting huge ranges in one shot.
Migrating from another FX API and hitting errors?
Request parameters follow common FX API conventions (base currency plus a symbols filter), so most migrations are a base-URL swap with no code rewrite. Where responses differ, this API adds fields (source, market_session, notice) rather than removing them, check any response-parsing code for a fixed key-set assumption.
The shortest call that works
No key, no dependencies:
curl https://api.exchangerate.dev/v1/latest/USDYou get back the rates plus source and market_session so you know how fresh each one is. A free key raises the limit to 5,000 calls a month and takes a minute.
Rates are for reference, analytics, and display, not trade settlement. Free permits commercial display with linked credit; paid plans need no credit. No plan allows redistribution.