Every error is JSON with result: "error", a code and a message. Limits are per minute and per month on each plan, and keyless callers are capped per IP. A 429 tells you how long to wait in Retry-After. All routes live under /v1, and /v1 only changes in additive ways.
Error format
An error response is JSON with three fields: result is always "error", code is machine readable and message is for people. Some errors add fields, such as tier, upgrade_url or retry_after_seconds. Branch on the HTTP status and code. The message text can change.
curl -i "https://api.exchangerate.dev/v1/latest/ZZZ"{ "result": "error", "code": "unsupported_base", "message": "unsupported base: ZZZ"}A request with a malformed parameter, including an invalid request body, returns 400 with code: invalid_request. A route that does not exist returns 404 with code: not_found. Every response, success or error, carries an X-Request-Id header. A request that sends its own UUID in that header gets it back.
A plan limit returns 403 with code: plan_gated, a message that says what the plan includes, and the fields that explain the gate. This request asks for daily history older than the Free plan's 30 days.
curl -i "https://api.exchangerate.dev/v1/range?base=USD&symbols=EUR&start_date=2020-01-01&end_date=2020-01-05"{ "result": "error", "code": "plan_gated", "message": "Your plan includes 30 days of 1d history.", "tier": "free_2026", "interval": "1d", "history_days": 30, "earliest_allowed": "2026-10-14", "upgrade_plans": [ "plus_2026", "pro_2026" ], "upgrade_url": "https://exchangerate.dev/pricing?plan=plus_2026&source=api&reason=plan_gated"}The example shows the fields that matter. The live response also lists upgrade_offers, and earliest_allowed moves with the date.
Error codes
These are the codes the API emits. The OpenAPI spec documents the error responses of every data route, and each endpoint page lists its own: latest, convert and historical.
| Status | code | When |
|---|---|---|
| 400 | unsupported_base | The base currency is not one of the 144 the API serves. |
| 400 | invalid_pair | A symbol in the request is not a supported currency. |
| 400 | invalid_amount | The amount is not a positive number. |
| 400 | bad_date | The date is invalid or out of range. An oversized /v1/range window also returns bad_date. |
| 400 | missing_parameter | A required parameter is missing. The message names it. |
| 400 | invalid_request | A parameter or body is malformed. |
| 400 | unsupported_interval, unsupported_pair_interval, unsupported_index_interval | The interval does not exist, is not served for that pair, or is not served for that index. |
| 401 | invalid_api_key | The API key is missing, invalid or revoked. |
| 403 | plan_gated | The plan excludes this interval or history depth. The response carries the gated fields and an upgrade hint. |
| 404 | no_data_for_date | No historical data for that date. |
| 404 | unknown_index | The index slug does not exist. |
| 404 | not_found | The route does not exist. |
| 429 | ip_rate_limited | A keyless caller is over the per-IP hourly cap. |
| 429 | rate_limited | Over the per-minute limit: the plan's for a key, the keyless limit for an IP. |
| 429 | quota_exceeded | The plan's monthly requests are used up. The response adds tier and monthly_quota, and an upgrade_url when a higher plan exists. |
| 429 | quota_unavailable | Usage metering could not be read. Retry after Retry-After. |
| 503 | data_unavailable | A rate the request needs is temporarily unavailable, or has no source at the moment. A suspended currency answers this way. |
| 503 | live_unavailable, source_unavailable | The data feed is temporarily unavailable. |
| 503 | service_unavailable | The request failed inside the API. Retry shortly. |
| 503 | auth_unavailable | The key could not be checked. Retry-After is 30 seconds. |
Rate limits and plan limits
Three limits apply. Requests a minute and requests a month come from the plan. Callers with no key are limited per IP: 10 a minute and 100 an hour. A batch conversion of N pairs counts as N calls against all three. Free plan limits has every plan as a table, and pricing has the prices.
| Plan | Requests a minute | Requests a month |
|---|---|---|
| No key (per IP) | 10, and 100 an hour | Not applicable |
| Free | 10 | 5,000 |
| Basic | 60 | 100,000 |
| Plus | 120 | 300,000 |
| Pro | 300 | 1,000,000 |
Free, keyless and website callers receive live rates 15 minutes late, and delayed answers carry X-Price-Delay-Seconds: 900. Paid plans receive live rates. ECB daily fixes are not delayed. History depth, intraday intervals and streaming also differ by plan, and a request outside the plan returns plan_gated.
Rate limit headers
| Header | Meaning |
|---|---|
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset | On metered /v1 reads and every 429. Not on keyless 2xx answers, which the edge caches for 5 seconds as Cache-Control: public, s-maxage=5. |
X-RateLimit-Scope | On a 429: anon-ip-hour, tier-rate-minute or tier-quota-month. |
Retry-After | On a 429: seconds to wait before retrying. |
X-Price-Delay-Seconds | 900 on delayed price, rate, index and time series answers. |
This is a keyless caller over the per-minute limit, run against the live API. The numbers change on every call.
retry-after: 19x-ratelimit-limit: 10x-ratelimit-remaining: 0x-ratelimit-reset: 1794543360x-ratelimit-scope: tier-rate-minute{ "result": "error", "code": "rate_limited", "message": "Per-minute rate limit exceeded for your tier.", "tier": "free_2026", "limit_per_minute": 10, "retry_after_seconds": 19}Retry guidance
Data endpoints are read-only GET requests, apart from batch conversion, which only reads rates. Repeating one changes nothing except your request count.
| Response | What to do |
|---|---|
429 rate_limited or ip_rate_limited | Wait Retry-After seconds, then retry. The same number is in retry_after_seconds in the body. |
429 quota_exceeded | Do not retry automatically. The month's requests are used up. Retry-After is the time to the reset. Wait for it or change plan. |
429 quota_unavailable | Retry after Retry-After. Metering could not be read. |
503 data_unavailable, live_unavailable, source_unavailable, service_unavailable | The failure is temporary. The message says to retry shortly. |
503 auth_unavailable | Retry after 30 seconds. The key was sent but could not be checked, and the request is not downgraded to keyless access. |
| 400, 401, 403, 404 | Do not retry the same request. Fix the base, symbols, date, key or plan first. |
A 200 can carry old or missing rates, so check these fields before you show or store a rate. sources and effective_at give each currency's source and observation time. stale flags a currency past its source's freshness window. unavailable lists named symbols that have no rate now. market_session says whether the market is open, closed for the weekend or interbank closed. timestamp is when the response was built, not when a rate was observed.
From Friday 17:00 to the Sunday open, New York time, rates hold their Friday close. A weekend response is not stale. market_session says it is closed. Daily history leaves today out until the day has closed, and a past date with no fix is carried forward and marked is_forward_filled: true.
Status and availability
There is no formal uptime guarantee. The Terms say there is no service level agreement, and any service credit is at our discretion. The status page is a live probe of five components: the API, the database, the rate-limit store, live data freshness and daily history freshness. Each is operational, degraded, stale or down. The page shows the current state and does not keep a history of past incidents.
The same probe is at GET /status on the API host and answers 503 with its payload when the service is down. GET /health is a liveness probe. Neither needs a key.
curl "https://api.exchangerate.dev/health"{ "status": "ok"}Cached edge answers are typically under 100 milliseconds. That is a typical figure, not a service level.
Versioning and stability
/v1 is the stability contract. Additive changes, such as a new field or a new error code, are not breaking and can arrive at any time, so ignore fields and codes you do not know. Removing a field or changing a type would ship as /v2. The OpenAPI spec describes every route.
No route is deprecated at the moment, and none sends a Deprecation or Sunset header. User-visible changes are listed in the changelog, which has a feed. Accounts on older plans keep their price and limits while they stay subscribed.