freecurrencyapi Documentation

# Request Status Codes

For all requests, we will return an HTTP status code that indicates a success or the problem that has led to the failure.

A successful request will be returned with status code 200

# API Error Codes

# 401

Invalid authentication credentials

# 403

You are not allowed to make this request — for example, the requested feature is not part of your plan (please upgrade your plan (opens new window)), the request's referrer is not on your API key's referrer whitelist, or the API key belongs to a different EverAPI product.

# 404

A requested endpoint does not exist

# 422

Validation error, please check the list of validation errors: here

# 429

You have hit your rate limit or your monthly limit. For more requests please upgrade your plan (opens new window).

# 500

Internal Server Error - let us know: support@freecurrencyapi.com

# Error response format

Error responses with status 401, 403, 404 and 429 carry a machine-readable envelope in addition to the human-readable message:

  • error.code — a stable, machine-readable error code (see the table below)
  • error.message — the same text as message
  • quota — only on quota errors: your limit, used, remaining and the resets_at timestamp of the next quota reset
  • actions — URLs for the most useful next steps, e.g. where to get an API key, upgrade your plan or find the machine-readable API specification
{
    "message": "Invalid authentication credentials",
    "error": {
        "code": "invalid_api_key",
        "message": "Invalid authentication credentials"
    },
    "actions": {
        "get_free_api_key": "https://api.freecurrencyapi.com/v1/agent/keys",
        "sign_up": "https://app.freecurrencyapi.com/register?utm_source=api_error&utm_campaign=invalid_api_key",
        "docs": "https://freecurrencyapi.com/docs/openapi.yaml"
    }
}
Status Possible error.code values
401 missing_api_key, invalid_api_key
403 forbidden, referrer_not_allowed, key_not_allowed_for_product
404 not_found
429 rate_limit_exceeded, quota_exceeded, grace_quota_exceeded, overage_quota_exceeded

# Validation errors

Validation errors are returned with status 422 and contain a message ("Validation error"), an errors object keyed by the offending parameter with one or more messages per parameter, and an info link back to this page.

# Invalid currencies

One of the selected currencies is invalid, to get a full list of all currencies you can use the currencies (opens new window) endpoint.

# Invalid base_currency

The selected base_currency is invalid, to get a full list of all currencies you can use the currencies (opens new window) endpoint.

# Invalid date

The date is not a valid date. Please use the following format: YYYY-MM-DD

The date must be between 1999-01-01 and yesterday.