DocsDocs

API reliability

Error format and codes, rate limits, retry rules, status, versioning and stability.

13 Nov 2026 · 6 min read

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.

Shell
curl -i "https://api.exchangerate.dev/v1/latest/ZZZ"
Response, 400
{  "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.

Shell
curl -i "https://api.exchangerate.dev/v1/range?base=USD&symbols=EUR&start_date=2020-01-01&end_date=2020-01-05"
Response, 403
{  "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.

StatuscodeWhen
400unsupported_baseThe base currency is not one of the 144 the API serves.
400invalid_pairA symbol in the request is not a supported currency.
400invalid_amountThe amount is not a positive number.
400bad_dateThe date is invalid or out of range. An oversized /v1/range window also returns bad_date.
400missing_parameterA required parameter is missing. The message names it.
400invalid_requestA parameter or body is malformed.
400unsupported_interval, unsupported_pair_interval, unsupported_index_intervalThe interval does not exist, is not served for that pair, or is not served for that index.
401invalid_api_keyThe API key is missing, invalid or revoked.
403plan_gatedThe plan excludes this interval or history depth. The response carries the gated fields and an upgrade hint.
404no_data_for_dateNo historical data for that date.
404unknown_indexThe index slug does not exist.
404not_foundThe route does not exist.
429ip_rate_limitedA keyless caller is over the per-IP hourly cap.
429rate_limitedOver the per-minute limit: the plan's for a key, the keyless limit for an IP.
429quota_exceededThe plan's monthly requests are used up. The response adds tier and monthly_quota, and an upgrade_url when a higher plan exists.
429quota_unavailableUsage metering could not be read. Retry after Retry-After.
503data_unavailableA rate the request needs is temporarily unavailable, or has no source at the moment. A suspended currency answers this way.
503live_unavailable, source_unavailableThe data feed is temporarily unavailable.
503service_unavailableThe request failed inside the API. Retry shortly.
503auth_unavailableThe 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.

PlanRequests a minuteRequests a month
No key (per IP)10, and 100 an hourNot applicable
Free105,000
Basic60100,000
Plus120300,000
Pro3001,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

HeaderMeaning
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetOn 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-ScopeOn a 429: anon-ip-hour, tier-rate-minute or tier-quota-month.
Retry-AfterOn a 429: seconds to wait before retrying.
X-Price-Delay-Seconds900 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.

Response headers, 429
retry-after: 19x-ratelimit-limit: 10x-ratelimit-remaining: 0x-ratelimit-reset: 1794543360x-ratelimit-scope: tier-rate-minute
Response body, 429
{  "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.

ResponseWhat to do
429 rate_limited or ip_rate_limitedWait Retry-After seconds, then retry. The same number is in retry_after_seconds in the body.
429 quota_exceededDo 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_unavailableRetry after Retry-After. Metering could not be read.
503 data_unavailable, live_unavailable, source_unavailable, service_unavailableThe failure is temporary. The message says to retry shortly.
503 auth_unavailableRetry after 30 seconds. The key was sent but could not be checked, and the request is not downgraded to keyless access.
400, 401, 403, 404Do 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.

Shell
curl "https://api.exchangerate.dev/health"
Response
{  "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.

Keep reading

Start with a free API key

Free includes every currency pair, 30 days of history, MCP, and commercial display with a visible link to exchangerate.dev.

Get a free key