Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code 200.

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting our support.

Status codes

Here is a list of the different categories of status codes returned by the currencyapi API. Use these to understand if a request was successful.

Name
200
Type
Description
A 200 status code indicates a successful response.
Name
401
Type
Description
A 401 status code indicates that your request did not carry a valid API key. If no key was sent at all, the message is "No API key found in request" (error code missing_api_key); if the key is not valid, it is "Unauthorized" (error code invalid_api_key). Double-check the key against your dashboard.
Name
403
Type
Description
A 403 status code indicates that you are not allowed to use this endpoint or parameter, please upgrade your plan. This happens when your plan does not include /convert or the range endpoint (/range, /ohlc, /official/range), when you request a range accuracy or an ohlc interval above your plan, when you send datetime to /rate or /convert on a plan with daily updates, or when your plan limits range requests to one currency and you request more.
Name
404
Type
Description
A 404 status code indicates that a requested endpoint does not exist. The rates endpoints also return a 404 when there is no data for your requested timeframe and accuracy: "We sadly do not have any data in this timeframe for the selected accuracy." The official rates endpoints return a 404 when the central bank published nothing on the requested date (or in the 14 days before it) or in the requested range. /fluctuation and /average return a 404 when no rates are stored for the requested days.
Name
405
Type
Description
A 405 status code indicates an HTTP method the endpoint does not take (error code method_not_allowed); the Allow header names those it does. A HEAD request answers 405 on every billed endpoint, without running it and without being billed; /v3/status and the other free endpoints answer HEAD like GET.
Name
422
Type
Description
A validation error, please check the list of validation errors: here
Name
429
Type
Description
A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests please upgrade your plan.
Name
500
Type
Description
A 500 status code indicates an internal server error - let us know: support@currencyapi.com

Error response body

Every error response contains a human-readable message. The rest of the body depends on the kind of error:

403, 404 and 422 responses produced by the API endpoints additionally carry an info link pointing back to this page. Validation errors (422) also include an errors object that maps each invalid parameter to a list of validation messages. The official rates endpoints link their own page instead and also carry the error envelope described below.
401, 403, 404 and 429 responses carry a machine-readable envelope: an error object with a stable code (e.g. missing_api_key, invalid_api_key, plan_upgrade_required when your plan does not include an endpoint or parameter, not_found when there is no data, rate_limit_exceeded) and message, plus an actions object with next-step URLs. Monthly-quota 429 responses additionally include a quota object with limit, used, remaining and resets_at; minute rate-limit 429 responses do not.

Example validation error response

{
    "message": "Validation error",
    "errors": {
        "base_currency": [
            "The selected base currency is invalid."
        ]
    },
    "info": "For more information, see documentation: https://currencyapi.com/docs/status-codes#_422"
}

Example 401 error response

{
    "message": "Unauthorized",
    "error": {
        "code": "invalid_api_key",
        "message": "Unauthorized"
    },
    "actions": {
        "sign_up": "https://app.currencyapi.com/register?utm_source=api_error&utm_campaign=invalid_api_key",
        "docs": "https://currencyapi.com/docs/openapi.yaml"
    }
}

Validation errors

Here is a list of the validation error messages returned by the currencyapi API with a 422 status code, and what each of them means.

Name
Invalid currencies
Type
Description
One of the selected currencies is invalid, to get a full list of all currencies you can use the /currencies endpoint.
Name
Invalid base_currency
Type
Description
The selected base_currency is invalid, to get a full list of all currencies you can use the /currencies endpoint.
Name
Invalid date
Type
Description
The date is not a valid date. Please use the following format: YYYY-MM-DD
Name
Chronological order issue: datetime_start
Type
Description
The datetime_start must be a date before or equal to datetime_end
Name
Invalid datetime_start
Type
Description
The datetime_start is not a valid date. Datetime for the start of your requested range (format: 2021-12-31T23:59:59Z / ISO8601 Datetime)
Name
Chronological order issue: datetime_end
Type
Description
The datetime_end must be a date after or equal to datetime_start
Name
Invalid datetime_end
Type
Description
The datetime_end is not a valid date. Datetime for the end of your requested range (format: 2021-12-31T23:59:59Z / ISO8601 Datetime)
Name
Invalid accuracy
Type
Description
The selected accuracy is invalid. Possible Values: day, hour, quarter_hour, minute, week, month, default: day
Name
Invalid date_from / date_to
Type
Description
Used by /fluctuation and /average: both must be days in YYYY-MM-DD format between 1999-01-01 and yesterday, with date_from on or before date_to.
Name
Span too long
Type
Description
date_from and date_to must not be more than 1830 days apart (366 days for official averages with source).
Name
Invalid period
Type
Description
The selected period is invalid. Possible Values: month, quarter, year, total, default: month