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 "Invalid authentication credentials" (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, please upgrade your plan.
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."
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.
401 and 429 responses instead carry a machine-readable envelope: an error object with a stable code (e.g. missing_api_key, invalid_api_key, 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": "Invalid authentication credentials",
    "error": {
        "code": "invalid_api_key",
        "message": "Invalid authentication credentials"
    },
    "actions": {
        "get_free_api_key": "https://api.currencyapi.com/v1/agent/keys",
        "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_start must be a date before or equal to datetime_end
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, default: day