API Reference

Error Codes

Complete reference for all CurrencyCore API error codes and how to handle them.

All errors follow a consistent JSON envelope:

{
  "error": {
    "code": "unknown_currency",
    "message": "Currency code 'XYZ' is not recognized.",
    "details": {}
  }
}

Error code reference

HTTP status	Code	Meaning	Resolution
`400`	`invalid_input`	A required parameter is missing or has an invalid format (e.g., non-numeric `amount`).	Check your query parameters against the /convert docs.
`400`	`missing_ppp_countries`	`ppp=true` was passed but a currency (`from` or a `to`) has no country.	Pair every currency with its country as `CUR:COUNTRY` (e.g. `from=USD:USA&to=INR:IND,EUR:DEU`).
`400`	`unknown_currency`	The `from` or `to` currency code is not a recognized ISO 4217 code.	Verify the currency code (e.g., `USD`, `EUR`, `INR`).
`400`	`unknown_ppp`	No PPP factor exists for the specified country/year combination.	Check the country code is ISO/IMF alpha-3 (e.g. `USA`, `IND` — see /countries).
`404`	`rate_not_found`	No exchange rate data is available for the requested `date`.	Use a more recent date or omit `date` to use the latest available.
`401`	`unauthorized`	The `Authorization` header is missing or the key does not exist.	Provide a valid `Authorization: Bearer cc_live_...` header.
`403`	`forbidden`	The API key exists but is disabled or lacks access to the resource.	Check the key status in the dashboard and re-enable if needed.
`429`	`rate_limited`	You have exceeded your per-minute request limit.	Wait for the `Retry-After` header value (in seconds) before retrying.
`403`	`free_tier_org_limit`	Your organization has reached its monthly request quota.	Upgrade your plan in the dashboard.
`500`	`internal_error`	An unexpected error occurred on the server.	Retry with exponential back-off. If persistent, contact support.

Retrying requests

429: Honor the Retry-After response header.
500: Retry with exponential back-off (e.g., 1s, 2s, 4s). Most transient errors resolve within seconds.
400 / 401 / 403 / 404: These are client errors — retrying the same request without changes will return the same error.

TypeScript

All error codes are available as a typed constant from @currencycore/shared:

import { ERROR_CODES, type ApiError } from "@currencycore/shared";

if (data.error?.code === ERROR_CODES.RATE_LIMITED) {
  // handle rate limit
}