Documentation

POST /v1/auth/login was given an email that has no account, or the right email with the wrong password. The two cases are deliberately reported identically so the endpoint cannot be used to test whether an address is registered.

Fix: Check the email and password. Reset the password from the login page if you are unsure.

Reserved. No route emits this code today: an expired dashboard token fails signature and expiry verification in one step and comes back as TOKEN_INVALID.

Fix: Handle it as you would TOKEN_INVALID, by refreshing the session token.

The dashboard token in the Authorization header did not verify. It is malformed, signed with another secret, or past its expiry. Applies to /v1/keys, /v1/billing, /v1/me and the token refresh and password reset routes.

Fix: Sign in again to obtain a fresh token. This code never applies to API keys, which use X-API-Key.

No credential was presented where one is required. Either the API key is missing from both the X-API-Key header and the api_key query parameter, or the Authorization header is absent or not a Bearer token, or the token verified but its user no longer exists.

Fix: Send the credential the route expects: X-API-Key for the data endpoints, Bearer token for the dashboard endpoints.

Reserved. No route emits this code any more. POST /v1/auth/register used to answer it when the address was already taken, which turned sign-up into a way of testing whether a given address has an account here. Registration now answers the same thing in every case and moves the difference into the email it sends: a confirmation link if the address was free, a note that an account already exists if it was not.

Fix: Nothing to branch on. Registration always returns 200 with the same message; the mailbox holds the answer.

POST /v1/keys was called by an account whose email address has never been confirmed. Signing up sends a confirmation link, and until it is used the account can sign in and read the dashboard but cannot create an API key.

Fix: Open the link in the confirmation email. If it has expired, is lost, or was never received, request a new one from the banner in the dashboard or with POST /v1/auth/resend, which takes {"email": "..."} and answers identically whatever the state of the address. Completing a password reset also confirms the address, since it proves the same thing.

The API key presented does not match any key on record. Usually a truncated copy and paste, a key from another environment, or a stray whitespace character.

Fix: Copy the key again from the dashboard. Keys are shown once at creation and cannot be read back afterwards.

The key exists but has been revoked. Revocation is permanent and takes effect within the five-minute lifetime of the cached authentication session.

Fix: Create a new key from the dashboard and roll it out.

Reserved. No route emits this code today: deleting a key that does not belong to you, or does not exist, succeeds silently rather than reporting the difference.

Fix: Nothing to do. List your keys to confirm the current state.

The monthly request quota for the key owner is used up. The quota is counted per calendar month in UTC across every key on the account, and it is 10,000 on Free, 1,000,000 on Pro and unlimited on Scale.

Fix: Wait for the reset given by X-RateLimit-Reset and Retry-After, or upgrade the plan. X-RateLimit-Remaining tells you how much is left before you get here.

A ceiling on request frequency was hit. On the data endpoints it is 120 requests per minute, counted per source IP per key owner in fixed one-minute buckets, on every plan including Scale. The unauthenticated routes have their own, tighter, per-IP ceilings: sign-in 10 per 5 minutes and 60 per hour; sign-up 5 per hour and 20 per day; forgotten password and confirmation resend 3 per hour and 10 per day; token submission 30 per hour; the contact form 3 per hour and 10 per day. The routes that send an email are metered a second time per destination address, at 3 per hour and 10 per day, so no one can be mailbombed through them from many sources.

Fix: Back off for the number of seconds in Retry-After and spread the traffic. These ceilings are separate from the monthly quota and cannot be lifted by upgrading.

A currency code in the request is not in the snapshot or series being read. On the live endpoints that means it is outside the 170 codes listed by /v1/currencies or absent from the current snapshot. On /v1/historical and /v1/time-series it usually means the code is outside the ECB reference series, which is far narrower than /v1/currencies.

Fix: Check the code against /v1/currencies for live rates, and against the 47-code list documented under time-series for history. The message names the offending codes.

The pair parameter on /v1/fx/quote was missing or was not exactly 6 characters.

Fix: Concatenate the two ISO codes with no separator, as in EURUSD.

Too many currencies in one call. The ceiling is 50 targets on /v1/fetch-multi and /v1/historical, and 20 currencies on /v1/fetch-matrix, where the response grows as the square of the count.

Fix: Split the request, or call /v1/fetch-all and select what you need client side.

The endpoint is not included in the calling key plan. History, the FX and crypto endpoints and the WebSocket stream all need Pro or higher; Free carries the live fiat endpoints only.

Fix: Upgrade the plan, or use an endpoint your plan includes. The access table above lists which plan unlocks what.

Reserved. No route emits this code today: a plan without history returns PLAN_REQUIRED, and a date outside the plan window returns DATE_OUT_OF_RANGE.

Fix: Handle PLAN_REQUIRED and DATE_OUT_OF_RANGE instead.

A date is outside a boundary. It is 400 when the date is in the future, before 1999-01-04 on /v1/time-series, or when the requested range is wider than the allowed span. It is 403 when the date is further back than the plan allows, which is 10 years on Pro and, on Scale, further back than the series itself goes.

Fix: Read the message, which states the boundary that was crossed and the value it holds. Split wide ranges into windows of at most 1830 days.

The data exists in principle but no source could serve it right now: no cached snapshot at all, the historical provider unreachable, the crypto upstream failing, or the streaming backend refusing the upgrade.

Fix: Retry with a backoff. Unlike NOT_SUPPORTED, this one is temporary. Check the status page or /v1/status if it persists.

Reserved. Staleness is never reported as an error, because a stale rate is still an answer. It is reported inside every successful response as meta.stale, which turns true when the snapshot being served is flagged stale by the feeder.

Fix: Read meta.stale and the updated field on each response and decide your own tolerance. /v1/status publishes the age of the feeder snapshot.

The request is well formed and authorised, but the capability does not exist and is not coming back. Today this is only /v1/fx/ohlc. OHLC candles were removed rather than repaired: the previous implementation manufactured open, high and low around the current mid and returned a single bar whatever the period asked for. Our fiat source publishes one figure per business day, so there is no intraday path from which a candle could be derived.

Fix: Never retry this one. Use /v1/time-series for the daily close series over a range, or /v1/fx/quote for the current reference mid.

The request is malformed: a required parameter is missing, a date is not YYYY-MM-DD, start_date is after end_date, amount is not a positive number, or a request body failed validation. On /v1/stream it is also returned with status 426 when a plain HTTP GET arrives without a WebSocket upgrade.

Fix: The message names the parameter at fault. On /v1/stream, connect with a WebSocket client rather than curl.

No route matches this method and path. Note that the docs link on this particular error points at the docs root rather than at this anchor.

Fix: Check the path against the endpoint list above, including the /v1 prefix.

An unhandled exception. The response carries no detail on purpose; the detail is in our logs, keyed by request_id.

Fix: Retry once, then send us the request_id through the contact page if it repeats.