Documentation

Error Codes

This is the new v2 documentation: Released in February 2026.

Version v1 will be removed in 31st July 2026. Please see our migration guide to upgrade.

This page provides a comprehensive list of all error codes that the CurrencyApi.net API can return. Understanding these error codes will help you handle errors gracefully in your applications and provide better user experiences.

All error responses follow a consistent format and include an error code, message, and HTTP status code to help you identify and resolve issues quickly.

Overview

When an error occurs, the API will return an HTTP error status code along with a JSON or XML response containing the error details. The error response includes:

  • Error Code: A specific numeric code identifying the type of error
  • Error Message: A human-readable description of what went wrong
  • HTTP Status Code: The standard HTTP status code (400, 401, 403, 404, 429, 500)

Use the error code to determine the specific issue and provide appropriate feedback to your users.

Error Response Format

All error responses follow a consistent JSON and XML format. The response includes the error code, message, and HTTP status code.

Error Response Properties

valid boolean

Always false for error responses

error object

Object containing error details

code number

The specific error code (400-500)

message string

Human-readable error message

Error Codes Reference

Below is the complete list of all error codes that the API can return:

All Error Codes

400 number

You did not supply an API key

401 number

Your API key is not valid

405 number

You have hit your monthly subscription allowance

406 number

You've requested a base currency that doesn't exist

414 number

One or more of the currencies is not a currency we support or has been entered invalid

416 number

Your subscription plan does not allow you to use this endpoint

417 number

There is no historical data for the date supplied

418 number

One or more of the dates you supplied were not in the correct format (eg 2026-01-01)

419 number

We allow a maximum of 365 days. Please change this and try again

420 number

You have requested either today's date or a date in the future. For timeframe and history endpoints, we store the data at 23:59 GTM of the current day

421 number

There is no OHLC data available for the date supplied

422 number

There is no OHLC data available for the requested currency on this date

423 number

The interval parameter is invalid. Allowed values: 5m, 15m, 30m, 1h, 4h, 12h, 1d

424 number

OHLC data is only available for the last 30 days.

500 number

There seems to be a technical fault our end

Best Practices

To handle errors effectively in your applications:

  • Always check the valid field: This indicates whether the request was successful
  • Handle specific error codes: Use the error code to provide specific user feedback
  • Implement retry logic: For rate limit errors (405), implement exponential backoff
  • Log errors appropriately: Include error codes and messages in your application logs
  • Provide user-friendly messages: Translate technical error messages into user-friendly text
  • Monitor error rates: Track error frequencies to identify issues early
  • Handle subscription limits: Check for subscription-related errors (405, 407, 408, 416) and guide users to upgrade