> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ca.cryptoprocessing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API errors

CryptoProcessing uses conventional HTTP response codes to indicate the success or failure of an API request: `2xx` for success and `4xx` for errors. The sections below cover the `4xx` codes this API returns.

## General errors

These errors aren't tied to a particular endpoint. Errors that only some endpoints return are listed under [Errors by endpoint](#errors-by-endpoint).

### Bad content format - 400 Bad Request

```json theme={null}
{"error":"Bad content format", "code":"bad_content_format"}
```

This error can occur for the following reasons:

* **Malformed or invalid JSON.** The request body could not be parsed. Ensure it is valid JSON.
* **Missing Content-Type header.** The `Content-Type` header must be set to `application/json`.

### Bad signature header - 403 Forbidden

```json theme={null}
{"error":"Bad signature header", "code":"bad_header_signature"}
```

The value in `X-Processing-Signature` did not match the request body, or the value in `X-Processing-Key` did not match any active API key. See [Authentication](https://docs.ca.cryptoprocessing.com/api-reference/authentication.md) for how to generate the signature correctly. This can happen for several reasons:

* **Signature not converted to string.** The signature is generated from a data array without first converting it to a string. Ensure the signature value is sent as a string.
* **Wrong hashing algorithm.** The signature must be generated using HMAC-**SHA-512** — a signature generated with SHA-256, SHA-1, or another digest will not match, even if everything else about the request is correct.
* **Body modified after signing.** The signed body must be identical to the body that is sent — no reformatting, whitespace changes, or field reordering.
* **Extra characters or spaces.** A code error introduces unexpected characters or spaces. Review your implementation and verify no extra characters are present.
* **Signature built from the full data array.** The signature is created from the entire data array — including the public key and headers — instead of the secret key only. Generate the signature exclusively from the secret key.
* **Public key in wrong parameter (PHP).** In some languages such as PHP, the public key may be mistakenly included in `paramsArray` instead of the request body. Pass the public key in the correct location.
* **Wrong secret key or environment.** Sandbox and production use separate key pairs. Make sure you are using the correct set for the environment you are targeting, and that the base URL matches it.
* **Non-whitelisted IP.** If you have configured an IP whitelist in the portal, requests from any unlisted IP will be rejected. Add the IP to the whitelist, use an already-whitelisted IP, or remove the whitelist entirely.
* **Deactivated or archived key.** The key exists but can't authenticate requests. [Reactivate](https://docs.ca.cryptoprocessing.com/merchant-administration/manage-api-keys.md#deactivate-an-api-key) a deactivated key. An archived key can't be reactivated, so [generate and activate a new one](https://docs.ca.cryptoprocessing.com/merchant-administration/generate-and-activate-api-keys.md).
* **Incorrect or malformed public key.** Verify you are using the correct key. It contains both upper and lower case characters and must be sent exactly as provided — avoid any case transformation in your code.
* **Secret key used instead of public key.** The `X-Processing-Key` header must contain your public key only. The secret key is used exclusively to generate and verify signatures. Refer to [Get your API key](https://docs.ca.cryptoprocessing.com/merchant-administration/generate-and-activate-api-keys.md) for details.
* **Completely empty request body in Postman.** Your Postman collection's pre-request script may be handling empty bodies incorrectly. Download our [Postman collection](https://docs.ca.cryptoprocessing.com/api-reference/postman-collection.md), or send an empty JSON object (`{}`) instead.

### No signature header - 403 Forbidden

```json theme={null}
{"error":"No signature header", "code":"required_header_signature"}
```

The request does not include the required `X-Processing-Signature` header, or the header is present but empty — an empty value is treated the same as a missing header. Add it with an HMAC-SHA512 signature of the request body.

### No key header - 403 Forbidden

```json theme={null}
{"error":"No key header", "code":"required_header_key"}
```

This error can occur for the following reasons:

* **Missing X-Processing-Key header.** Add the `X-Processing-Key` header with your public API key. A header that's present but empty is treated the same as a missing header.
* **Invalid request URL.** Verify the endpoint URL is correct.

### API key does not have the required ability - 403 Forbidden

```json theme={null}
{"error":"The API key does not have access to this endpoint.", "code":"api_key_ability_required"}
```

The Custom API key is valid, but the requested endpoint isn't one of its abilities. A Custom key can only call these endpoints, each one only if the key has its ability (see [Generate a Custom key](https://docs.ca.cryptoprocessing.com/merchant-administration/generate-and-activate-api-keys.md#generate-a-custom-key)):

* [/v2/accounts/list](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/accounts-list.md)
* [/v2/transactions/info](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/transactions-info.md)
* [/v2/currencies/rates](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md)
* [/v2/currencies/list](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-list.md)

If you need one of these endpoints, [add its ability to the key](https://docs.ca.cryptoprocessing.com/merchant-administration/manage-api-keys.md#change-the-name-or-permissions-of-an-api-key). Every other endpoint, such as those for deposit addresses, withdrawals and exchanges, requires the Master key.

### Internal error - 422 Unprocessable Entity

```json theme={null}
{"errors":["Internal error"], "error_code":"internal_error"}
```

The request was understood but couldn't be completed because of an internal error. The message can also be `Something went wrong. Please try later.` or `Something went wrong.`, always with the `error_code` `internal_error`. Try the request again later.

### Too many requests - 429 Too Many Requests

You sent too many requests in a short time. The limit is counted per API key, not per IP address, so requests from all your servers that use the same key count together. Wait before you send the request again, and if you get `429` again, retry with an increasing delay between attempts.

### 404 Not Found

```json theme={null}
{"message":"Not found"}
```

This generic `404` is returned for a request:

* To a real endpoint path, using an HTTP method the endpoint doesn't support, for example `GET` on an endpoint that only accepts `POST`.
* To a path that doesn't correspond to any endpoint.

### 405 Method Not Allowed

Unlike the other codes on this page, `405` isn't returned by CryptoProcessing's API at all — a request only gets this when it never reaches the API in the first place, and the response is a plain HTML page instead of JSON. This happens when the URL is missing `/api` (e.g. `https://app.ca.cryptoprocessing.com/v2/...` instead of `https://app.ca.cryptoprocessing.com/api/v2/...`) or otherwise doesn't match the base URL in [Introduction](https://docs.ca.cryptoprocessing.com/api-reference/introduction.md) — the request lands on a different service at the same host instead of this API. A `GET` request to such a URL gets a `200` response with an HTML web page instead, so a status check should look at the body too (see [Check API status](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/ping.md)).

## Errors by endpoint

Each section below lists the errors one endpoint returns for its own request, by status code, in addition to the [general errors](#general-errors).

### Generate a user deposit address

`POST /v2/addresses/take` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/addresses-take.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `currency: The currency field is required.` | `currency` is missing. |
| `currency: The currency must be a string.` | `currency` was sent as another JSON type, such as a number. |
| `foreign_id: The foreign id field is required.` | `foreign_id` is missing. |
| `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. |
| `currency: Invalid currency` | <ul><li>The `currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md).</li><li>`currency` is a fiat currency. A deposit address is always for a cryptocurrency: to have deposits added to your balance in a fiat currency, set `convert_to` to the fiat currency you want to receive.</li></ul> |
| `currency: Currency is not allowed without conversion` | Deposits in this currency are only accepted with automatic conversion. Specify `convert_to`. |
| `convert_to: Invalid currency` | <ul><li>The `convert_to` code doesn't exist.</li><li>`convert_to` is the same as `currency`. To accept deposits without conversion, leave `convert_to` out.</li><li>Deposits in `currency` can't be converted to `convert_to`. [/v2/currencies/rates](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md) lists the pairs you can use.</li></ul> |
| `convert_to: Currency is not allowed without conversion` | The `convert_to` currency can't be used for automatic conversion of deposits. |
| `end_user_reference: The end user reference field is required.` | `end_user_reference` is missing. |
| `end_user_reference: The end user reference must not contain email.` | `end_user_reference` contains an email address. Use an ID from your system that contains no personal data. |
| `sender_type: The sender type field is required.` | `sender_type` is missing. |
| `sender_type: The selected sender type is invalid.` | `sender_type` isn't `natural` or `legal`. |
| `sender_data: The sender data field is required.` | `sender_data` is missing or an empty object. |
| `sender_data: The sender data must be an array.` | `sender_data` isn't a JSON object, for example a string. |
| `sender_data.first_name: The sender data.first name field is required.` | `sender_type` is `natural`, and `sender_data.first_name` is missing. |
| `sender_data.first_name: The sender data.first name may not be greater than 255 characters.` | `sender_data.first_name` is longer than 255 characters. |
| `sender_data.last_name: The sender data.last name field is required.` | `sender_type` is `natural`, and `sender_data.last_name` is missing. |
| `sender_data.last_name: The sender data.last name may not be greater than 255 characters.` | `sender_data.last_name` is longer than 255 characters. |
| `sender_data.date_of_birth: The sender data.date of birth does not match the format Y-m-d.` | `sender_data.date_of_birth` isn't a date in the YYYY-MM-DD format. |
| `sender_data.legal_name: The sender data.legal name field is required.` | `sender_type` is `legal`, and `sender_data.legal_name` is missing. |
| `sender_data.legal_name: The sender data.legal name may not be greater than 255 characters.` | `sender_data.legal_name` is longer than 255 characters. |
| `sender_data.country_of_registration: The sender data.country of registration field is required.` | `sender_type` is `legal`, and `sender_data.country_of_registration` is missing. |
| `sender_data.country_of_registration: The selected sender data.country of registration is invalid.` | `sender_data.country_of_registration` isn't a three-letter ISO 3166-1 alpha-3 country code, either because it has the wrong length or because no country has that code. |
| `sender_data: Address cannot be issued for that end_user_reference` | No new address can be issued for this `end_user_reference`. |

**422 Unprocessable Entity**

| Error message | What it means |
| - | - |
| `Something went wrong, please try again shortly` (code `blockchain_error`) | The address couldn't be issued because of a temporary problem. Try again shortly. |

### Withdraw crypto

`POST /v2/withdrawal/crypto` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/withdrawal-crypto.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `currency: The currency field is required.` | `currency` is missing, `null` or an empty string. |
| `currency: Invalid currency` | <ul><li>The `currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md).</li><li>`currency` is a fiat currency, but `convert_to` is missing. To withdraw from a fiat balance, set `convert_to` to the cryptocurrency to send.</li></ul> |
| `currency: The currency must be a string.` | `currency` was sent as another JSON type, such as a number. |
| `convert_to: Invalid currency` | <ul><li>The `convert_to` code doesn't exist.</li><li>`convert_to` is the same as `currency`. To withdraw without conversion, leave `convert_to` out.</li><li>`convert_to` is a fiat currency. Funds are sent in a cryptocurrency, so `convert_to` must be one.</li></ul> |
| `amount: The amount field is required when the amount to field is not presented.` | Neither `amount` nor `amount_to` was sent. Send one of them. |
| `amount: The amount must be a number.` | `amount` isn't a number or a numeric string. |
| `amount: The amount must be greater than 0.` | `amount` is zero or negative. |
| `amount: The amount is invalid. Max decimal places allowed: 2` | `currency` is a fiat currency and `amount` has more than 2 decimal places. |
| `amount: The amount must be at least <amount>.` | The amount is below the minimum withdrawal for the currency sent to the address (the `convert_to` currency, if set). `<amount>` is that minimum, in that currency; the message doesn't name the currency. |
| `amount: The requested amount exceeds the available balance.` | Your balance in `currency` is lower than the amount to withdraw. |
| `amount: Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.` | The conversion to `convert_to` can't be made for this amount at the moment. Try a smaller amount, or try again later. |
| `amount_to: The amount to field is required when the amount field is not presented.` | Neither `amount` nor `amount_to` was sent. Send one of them. |
| `amount_to: The amount to field can not be used when the amount field is presented.` | Both `amount` and `amount_to` were sent. Send only one of them. |
| `amount_to: The amount to must be a number.` | `amount_to` isn't a number or a numeric string. |
| `amount_to: The amount to must be greater than 0.` | `amount_to` is zero or negative. |
| `amount_to: The amount to must not have more than <decimals> decimal places.` | `amount_to` has more decimal places than the `convert_to` currency allows. |
| `amount_to: Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.` | The conversion can't be made for this `amount_to` at the moment. Try a smaller amount, or try again later. |
| `convert_to: The convert to field is required when amount to is present.` | `amount_to` was sent without `convert_to`. `amount_to` is an amount in the `convert_to` currency, so it only works with a conversion. |
| `address: The address field is required.` | `address` is missing, `null` or an empty string. |
| `address: The address must be a string.` | `address` was sent as another JSON type, such as a number. |
| `address: Invalid <currency> address` | The address isn't a valid address for the currency sent to it (the `convert_to` currency, if set), for example an address of another network. `<currency>` is that currency's code. |
| `tag: Currency <currency> does not support tags.` | A `tag` was sent for a currency that doesn't use tags. Leave `tag` out for this currency. |
| `tag: Tag is invalid` | The tag isn't valid for the currency, for example a destination tag that isn't a number. |
| `foreign_id: The foreign id field is required.` | `foreign_id` is missing, `null` or an empty string. |
| `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. |
| `foreign_id: The foreign id has already been taken.` | The `foreign_id` was already used by one of your withdrawals (from any of the three withdrawal endpoints) or exchanges (`/v2/exchange/fixed`, `/v2/exchange/now`). The check is case-insensitive. Use a new `foreign_id`. |
| `end_user_reference: The end user reference must not contain email.` | `end_user_reference` contains an email address. Use an ID from your system that contains no personal data. |
| `end_user_reference: The end user reference must be a string.` | `end_user_reference` was sent as another JSON type, such as a number. |
| `sender_type: The selected sender type is invalid.` | `sender_type` isn't `natural` or `legal`. |
| `receiver_type: The selected receiver type is invalid.` | `receiver_type` isn't `natural`, `legal` or `self`. |
| `receiver_data: The receiver data field is required.` | `receiver_data` is missing. It's required unless `receiver_type` is `self`. |
| `receiver_data.legal_name: The receiver data.legal name field is required.` | `receiver_type` is `legal`, and `receiver_data.legal_name` is missing. |
| `receiver_data.country_of_registration: The receiver data.country of registration field is required.` | `receiver_type` is `legal`, and `receiver_data.country_of_registration` is missing. |

**403 Forbidden**

| Error message | What it means |
| - | - |
| `Withdrawal functionality is currently unavailable` (code `withdrawal_functionality_unavailable`) | Withdrawals are disabled for your merchant account, so no new withdrawal can be created. See [Enable withdrawals again](https://docs.ca.cryptoprocessing.com/merchant-administration/disable-withdrawals.md#enable-withdrawals-again). |
| `Withdrawals are disabled for this API key.` (code `api_key_withdrawals_disabled`) | **Allow withdrawals** is turned off for the Master key you used. [Turn on **Allow withdrawals**](https://docs.ca.cryptoprocessing.com/merchant-administration/manage-api-keys.md#change-the-name-or-permissions-of-an-api-key) for the key. |

**422 Unprocessable Entity**

| Error message | What it means |
| - | - |
| `Internal error` (code `internal_error`) | An amount (`amount` or `amount_to`) was sent as a string in scientific notation, such as `"5e0"`. Send amounts in plain decimal notation, such as `"5"`. For other causes of this error, see [Internal error](#internal-error-422-unprocessable-entity). |

### Withdraw crypto instantly

`POST /v2/crypto/withdrawal_instant` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/crypto-withdrawal-instant.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `sender_currency: The sender currency field is required.` | `sender_currency` is missing, `null` or an empty string. |
| `sender_currency: The selected sender currency is invalid.` | The `sender_currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). |
| `sender_currency: Instant withdrawals are not supported for the specified sender_currency.` | <ul><li>The currency doesn't support [instant withdrawals](https://docs.ca.cryptoprocessing.com/withdrawals.md#instant-withdrawals).</li><li>`sender_currency` is a fiat currency.</li></ul> |
| `sender_currency: Instant withdrawals are disabled for this merchant.` | The currency supports instant withdrawals, but they aren't enabled for your account in this currency. |
| `sender_currency: The sender currency must be a string.` | `sender_currency` was sent as another JSON type, such as a number. |
| `sender_amount: The sender amount field is required.` | `sender_amount` is missing, `null` or an empty string. |
| `sender_amount: The sender amount must be a number.` | `sender_amount` isn't a number or a numeric string. |
| `sender_amount: The sender amount must be greater than 0.` | `sender_amount` is zero or negative. |
| `amount: The amount must be at least <amount>.` | `sender_amount` is below the minimum withdrawal for the currency. `<amount>` is that minimum; the message doesn't name the currency. Note the field: `amount`, not `sender_amount`. |
| `amount: The requested amount exceeds the available balance.` | Your balance in `sender_currency` is lower than `sender_amount`. Note the field: `amount`, not `sender_amount`. |
| `address: The address field is required.` | `address` is missing, `null` or an empty string. |
| `address: The address must be a string.` | `address` was sent as another JSON type, such as a number. |
| `address: Invalid <currency> address` | The address isn't a valid address for `sender_currency`, for example an address of another network. `<currency>` is that currency's code. |
| `foreign_id: The foreign id field is required.` | `foreign_id` is missing, `null` or an empty string. |
| `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. |
| `foreign_id: The foreign id has already been taken.` | The `foreign_id` was already used by one of your withdrawals (from any of the three withdrawal endpoints) or exchanges (`/v2/exchange/fixed`, `/v2/exchange/now`). The check is case-insensitive. Use a new `foreign_id`. |
| `end_user_reference: The end user reference must not contain email.` | `end_user_reference` contains an email address. Use an ID from your system that contains no personal data. |
| `end_user_reference: The end user reference must be a string.` | `end_user_reference` was sent as another JSON type, such as a number. |

**403 Forbidden**

| Error message | What it means |
| - | - |
| `Withdrawal functionality is currently unavailable` (code `withdrawal_functionality_unavailable`) | Withdrawals are disabled for your merchant account, so no new withdrawal can be created. See [Enable withdrawals again](https://docs.ca.cryptoprocessing.com/merchant-administration/disable-withdrawals.md#enable-withdrawals-again). |
| `Withdrawals are disabled for this API key.` (code `api_key_withdrawals_disabled`) | **Allow withdrawals** is turned off for the Master key you used. [Turn on **Allow withdrawals**](https://docs.ca.cryptoprocessing.com/merchant-administration/manage-api-keys.md#change-the-name-or-permissions-of-an-api-key) for the key. |

### Withdraw crypto instantly with conversion

`POST /v2/crypto/withdrawal_instant_exchange` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/crypto-withdrawal-instant-exchange.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `sender_currency: The sender currency field is required.` | `sender_currency` is missing, `null` or an empty string. |
| `sender_currency: The selected sender currency is invalid.` | The `sender_currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). |
| `sender_currency: The sender currency must be a string.` | `sender_currency` was sent as another JSON type, such as a number. |
| `received_currency: The received currency field is required.` | `received_currency` is missing, `null` or an empty string. |
| `received_currency: The selected received currency is invalid.` | The `received_currency` code doesn't exist. |
| `received_currency: Instant withdrawals are not supported for the specified received_currency.` | <ul><li>`received_currency` doesn't support [instant withdrawals](https://docs.ca.cryptoprocessing.com/withdrawals.md#instant-withdrawals).</li><li>`received_currency` is a fiat currency.</li></ul> |
| `received_currency: Instant withdrawals are disabled for this merchant.` | `received_currency` supports instant withdrawals, but they aren't enabled for your account in this currency. |
| `received_currency: The received currency must be a string.` | `received_currency` was sent as another JSON type, such as a number. |
| `convert_to: Invalid currency` | `received_currency` is the same as `sender_currency`. The error is keyed `convert_to`, a field this endpoint doesn't take. To withdraw without conversion, use [Withdraw crypto instantly](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/crypto-withdrawal-instant.md). |
| `sender_amount: The sender amount field is required.` | `sender_amount` is missing, `null` or an empty string. |
| `sender_amount: The sender amount must be a number.` | `sender_amount` isn't a number or a numeric string. |
| `sender_amount: The sender amount must be greater than 0.` | `sender_amount` is zero or negative. |
| `sender_amount: The amount is invalid. Max decimal places allowed: 2` | `sender_currency` is a fiat currency and `sender_amount` has more than 2 decimal places. |
| `amount: The amount must be at least <amount>.` | After conversion, the amount is below the minimum withdrawal for `received_currency`. `<amount>` is that minimum, in `received_currency`; the message doesn't name the currency. Note the field: `amount`, not `sender_amount`. |
| `amount: The requested amount exceeds the available balance.` | Your balance in `sender_currency` is lower than `sender_amount`. Note the field: `amount`, not `sender_amount`. |
| `amount: Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.` | The conversion to `received_currency` can't be made for this amount at the moment. Try a smaller amount, or try again later. |
| `address: The address field is required.` | `address` is missing, `null` or an empty string. |
| `address: The address must be a string.` | `address` was sent as another JSON type, such as a number. |
| `address: Invalid <currency> address` | The address isn't a valid address for `received_currency`, for example an address of another network. `<currency>` is that currency's code. |
| `foreign_id: The foreign id field is required.` | `foreign_id` is missing, `null` or an empty string. |
| `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. |
| `foreign_id: The foreign id has already been taken.` | The `foreign_id` was already used by one of your withdrawals (from any of the three withdrawal endpoints) or exchanges (`/v2/exchange/fixed`, `/v2/exchange/now`). The check is case-insensitive. Use a new `foreign_id`. |
| `end_user_reference: The end user reference must not contain email.` | `end_user_reference` contains an email address. Use an ID from your system that contains no personal data. |
| `end_user_reference: The end user reference must be a string.` | `end_user_reference` was sent as another JSON type, such as a number. |

**403 Forbidden**

| Error message | What it means |
| - | - |
| `Withdrawal functionality is currently unavailable` (code `withdrawal_functionality_unavailable`) | Withdrawals are disabled for your merchant account, so no new withdrawal can be created. See [Enable withdrawals again](https://docs.ca.cryptoprocessing.com/merchant-administration/disable-withdrawals.md#enable-withdrawals-again). |
| `Withdrawals are disabled for this API key.` (code `api_key_withdrawals_disabled`) | **Allow withdrawals** is turned off for the Master key you used. [Turn on **Allow withdrawals**](https://docs.ca.cryptoprocessing.com/merchant-administration/manage-api-keys.md#change-the-name-or-permissions-of-an-api-key) for the key. |

**422 Unprocessable Entity**

| Error message | What it means |
| - | - |
| `Internal error` (code `internal_error`) | `sender_amount` was sent as a string in scientific notation, such as `"2.5e1"`. Send amounts in plain decimal notation, such as `"25"`. For other causes of this error, see [Internal error](#internal-error-422-unprocessable-entity). |

### Create a payment request

`POST /payments/v1/requests` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/payments.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `Payment request with this foreign_id already exists.` | The `foreign_id` was already used by one of your payment requests. The check is case-insensitive. Use a new `foreign_id`. |
| `userFeePercent must be 0 or 100.` | `user_fee_percent` is neither `0` nor `100`. |
| `Amount is incorrect.` | `amount` isn't a number: for example, an empty string, text, or a number with spaces around it. |
| `Invalid request format.` | A field has the wrong JSON type, for example a string or fractional `life_time_duration`, a number `foreign_id`, a string `currency` or `payment_currency`, a number `currency.iso`, a string `user_fee_percent`, or `null` for `currency.iso` or an optional field. Send each field with its documented type, and leave out optional fields you don't use. |

**403 Forbidden**

| Error message | What it means |
| - | - |
| `Merchant is disabled.` | Your merchant account is disabled, so no payment request can be created. |

**404 Not Found**

| Error message | What it means |
| - | - |
| `Currency is incorrect.` | `currency.iso` is a code that can't be used for payment requests. See the [currency codes for payment requests](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md#currency-codes-for-payment-requests). |

**422 Unprocessable Entity**

| Error message | What it means |
| - | - |
| `The currency field is mandatory.` | `currency` is missing. |
| `Currency is a mandatory field.` | `currency.iso` is an empty string. |
| `Currency is incorrect.` | <ul><li>The `currency.iso` code doesn't exist among the [currency codes for payment requests](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md#currency-codes-for-payment-requests), which aren't always the codes other endpoints use.</li><li>`currency.iso` has a space before or after the code, for example `" EUR"`. Remove the spaces.</li></ul> |
| `The currency.iso is not available for the payment request.` | The currency exists, but can't be requested in a payment request. See the [currency codes for payment requests](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md#currency-codes-for-payment-requests). |
| `The iso is a mandatory field.` | `currency.iso` is missing. |
| `The currency.iso is disabled.` | The currency is disabled for your merchant account. Enable it in your [portal](https://docs.ca.cryptoprocessing.com/portal.md#enabling-and-disabling-currencies). |
| `The currency.network_name field is required for crypto currencies.` | `currency.iso` is a cryptocurrency, and `currency.network_name` is missing. |
| `The combination of currency and network is not supported.` | `currency.network_name` or `payment_currency.network_name` isn't a network that currency can be requested on, or isn't a network at all. See the [currency codes for payment requests](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md#currency-codes-for-payment-requests). |
| `The amount field is mandatory.` | `amount` is missing. |
| `Amount is a mandatory field it must be positive.` | `amount` is `null`, zero or negative. |
| `The minimum amount is <amount> <currency>.` | `amount` is below the [minimum payment request amount](https://docs.ca.cryptoprocessing.com/confirmations-and-limits.md). `<amount> <currency>` is the minimum, in the request's `currency`. For a request in a currency other than the one the minimum is set in, the minimum is converted at the current rate, and the amount in the message is slightly higher than the converted minimum. |
| `The maximum amount is <amount> <currency>.` | `amount` is above the [maximum payment request amount](https://docs.ca.cryptoprocessing.com/confirmations-and-limits.md). `<amount> <currency>` is the maximum, in the request's `currency`. For a request in a different currency from the one the maximum is set in, the maximum is converted at the current rate, and the amount in the message is slightly lower than the converted maximum. |
| `The amount for <currency> cannot have more than <decimals> decimal places.` | `amount` has more decimal places than payment requests allow for `currency`. `<decimals>` is the number allowed, which depends on the currency (2 for fiat currencies and stablecoins, 6 for other cryptocurrencies). |
| `It is obligatory - to fill in life_time_date_time or life_time_duration.` | Neither `life_time_duration` nor `life_time_date_time` was sent. Send one of them. |
| `Only one of fields life_time_date_time and life_time_duration should be field.` | Both `life_time_duration` and `life_time_date_time` were sent. Send only one of them. |
| `The lifespan must be longer than or equal to 5 minutes.` | <ul><li>The lifespan is shorter than the minimum for payment requests.</li><li>`life_time_date_time` is in the past.</li></ul> |
| `The lifespan must be shorter than or equal to 60 days.` | <ul><li>The lifespan is longer than the maximum for payment requests.</li><li>`life_time_date_time` is in milliseconds instead of seconds.</li></ul> |
| `The email address is incorrect.` | `end_user_email` isn't a valid email address. |
| `payment_currency must not be empty if provided.` | `payment_currency` was sent as an empty object. Leave it out instead. |
| `payment_currency.iso must be a cryptocurrency.` | `payment_currency.iso` is a fiat currency. The customer always pays in a cryptocurrency. |
| `payment_currency.iso must not be empty if provided.` | `payment_currency.iso` is an empty string. |
| `payment_currency.iso is incorrect.` | The `payment_currency.iso` code doesn't exist among the [currency codes for payment requests](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md#currency-codes-for-payment-requests). |
| `payment_currency.iso is disabled.` | The payment currency is disabled for your merchant account. Enable it in your [portal](https://docs.ca.cryptoprocessing.com/portal.md#enabling-and-disabling-currencies). |
| `Exchange rate is not available between <currency> and <payment_currency>.` | There's no exchange rate between `currency` and `payment_currency`, so the customer can't pay in that currency. Choose another `payment_currency`. |
| `payment_currency.network_name must not be empty if provided.` | `payment_currency.network_name` is an empty string. To accept the currency on any of its networks, leave `network_name` out. |
| `The description must be 255 characters or less.` | `description` is longer than 255 characters. |
| `The description must not be empty if provided.` | `description` is an empty string. Leave it out instead. |
| `Foreign ID must be 255 characters or less.` | `foreign_id` is longer than 255 characters. |
| `The foreign_id must not be empty if provided.` | `foreign_id` is an empty string. Leave it out instead. |
| `The url store is invalid.` | `url_store` isn't a valid HTTPS URL (an `http://` URL is rejected too). |
| `The url store must be 255 characters or less.` | `url_store` is longer than 255 characters. |
| `The url success is invalid.` | `url_success` isn't a valid HTTPS URL (an `http://` URL is rejected too). |
| `The url success must be 255 characters or less.` | `url_success` is longer than 255 characters. |
| `The url failed is invalid.` | `url_failed` isn't a valid HTTPS URL (an `http://` URL is rejected too). |
| `The url failed must be 255 characters or less.` | `url_failed` is longer than 255 characters. |
| `The end_user_reference must not be empty if provided.` | `end_user_reference` is an empty string. |
| `The end_user_reference must be 255 characters or less.` | `end_user_reference` is longer than 255 characters. |
| `The rate_mode must be either 'standard' or 'fixed'.` | `rate_mode` isn't `standard` or `fixed`. The value is case-sensitive. |
| `The payment_currency object is mandatory in fixed-rate mode.` | `rate_mode` is `fixed`, and `payment_currency` is missing. |
| `The iso field is mandatory.` | `payment_currency` was sent without `iso`, for example with only `network_name`. |
| `The payment_currency.network_name is mandatory in fixed-rate mode.` | `rate_mode` is `fixed`, and `payment_currency.network_name` is missing. |
| `The email is mandatory in fixed-rate mode.` | `rate_mode` is `fixed`, and `end_user_email` is missing. |
| `The sender_type is mandatory field in fixed-rate mode.` | `rate_mode` is `fixed`, and `sender_type` is missing. |
| `The sender_data is mandatory object in fixed-rate mode.` | `rate_mode` is `fixed`, and `sender_data` is missing. |
| `The sender_type is a mandatory field.` | `sender_type` is missing. |
| `The sender_type must be either ‘natural’ or ‘legal’.` | `sender_type` isn't `natural` or `legal`. |
| `The sender_data object is mandatory.` | `sender_data` is missing. |
| `The sender_data must be a valid object.` | `sender_data` isn't a JSON object. |
| `The first_name must be provided for sender_type = natural.` | `sender_type` is `natural`, and `sender_data.first_name` is missing. |
| `The first_name must be 255 characters or less.` | `sender_data.first_name` is longer than 255 characters. |
| `The last_name must be provided for sender_type = natural.` | `sender_type` is `natural`, and `sender_data.last_name` is missing. |
| `The last_name must be 255 characters or less.` | `sender_data.last_name` is longer than 255 characters. |
| `The date_of_birth must be in YYYY-MM-DD format.` | `sender_data.date_of_birth` isn't in the `YYYY-MM-DD` format. |
| `The legal_name must be provided for sender_type = legal.` | `sender_type` is `legal`, and `sender_data.legal_name` is missing. |
| `The legal_name must be 255 characters or less.` | `sender_data.legal_name` is longer than 255 characters. |
| `The country_of_registration must be provided for sender_type = legal.` | `sender_type` is `legal`, and `sender_data.country_of_registration` is missing. |
| `The country_of_registration must contain exactly 3 characters.` | `sender_data.country_of_registration` isn't 3 characters long. |
| `The country_of_registration must be a valid ISO Alpha-3 code.` | `sender_data.country_of_registration` isn't an ISO 3166-1 alpha-3 country code, such as `DEU`. |

### Exchange at market rate

`POST /v2/exchange/now` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/exchange-now.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `message: Exchange rate not available at this time` | The exchange rate for this pair isn't available at the moment. Try again later. |
| `sender_amount: Not enough balance. You have required at least <amount> <currency>` | Your balance in `sender_currency` is lower than this exchange needs. `<amount> <currency>` is the amount needed: the amount exchanged, plus the exchange fee when the fee is charged in `sender_currency`. |
| `sender_currency: The sender currency field is required.` | `sender_currency` is missing, `null` or an empty string. |
| `receiver_currency: The receiver currency field is required.` | `receiver_currency` is missing, `null` or an empty string. |
| `receiver_amount: The receiver amount field is required when the sender amount field is not presented.` | Neither `sender_amount` nor `receiver_amount` was sent. Send one of them. |
| `receiver_amount: The receiver amount field can not be used when the sender amount field is presented.` | Both `sender_amount` and `receiver_amount` were sent. Send only one of them. |
| `foreign_id: The foreign id field is required.` | `foreign_id` is missing, `null` or an empty string. |
| `receiver_currency: The receiver currency and sender currency must be different.` | `sender_currency` and `receiver_currency` are the same. (The same currency on another network has its own code; see [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md).) |
| `sender_currency: The selected sender currency is invalid.` | The `sender_currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). |
| `receiver_currency: The selected receiver currency is invalid.` | The `receiver_currency` code doesn't exist. |
| `sender_currency: The sender currency must be a string.` | `sender_currency` was sent as another JSON type, such as a number. |
| `sender_amount: The sender amount must be a number.` | `sender_amount` isn't a number or a numeric string. |
| `sender_amount: The sender amount must be greater than 0.` | `sender_amount` is zero or negative. |
| `receiver_amount: The receiver amount must be greater than 0.` | `receiver_amount` is zero or negative. |
| `sender_amount: The sender_amount must be at least <amount> <currency>` | `sender_amount` is below the minimum for this exchange. `<amount> <currency>` is that minimum, the `min_amount` of `sender_currency` in [/v2/currencies/rates](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md). |
| `receiver_amount: The receiver_amount must be at least <amount> <currency>` | `receiver_amount` is below the minimum for this exchange. `<amount> <currency>` is that minimum, the `min_amount` of `receiver_currency` in [/v2/currencies/rates](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md) for the pair in the opposite direction. |
| `sender_amount: The sender_amount may not be greater than <amount> <currency>` | `sender_amount` is above the maximum for one exchange. `<amount> <currency>` is that maximum. |
| `sender_amount: We can process only <decimals> decimal places` | `sender_amount` has more decimal places than this currency pair accepts for it. `<decimals>` is the number accepted, for example 2 for a fiat amount. Round `sender_amount` to `<decimals>` decimal places. |
| `receiver_amount: We can process only <decimals> decimal places` | `receiver_amount` has more decimal places than this currency pair accepts for it. `<decimals>` is the number accepted, for example 2 for a fiat amount. Round `receiver_amount` to `<decimals>` decimal places. |
| `foreign_id: The foreign id has already been taken.` | The `foreign_id` was already used by one of your exchanges (`/v2/exchange/fixed`, `/v2/exchange/now`) or withdrawals (from any of the three withdrawal endpoints). The check is case-insensitive. Use a new `foreign_id`. |
| `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. |
| `sender_amount: Exchange is unavailable for given currencies` | You can't exchange this currency pair: either it isn't a [supported trading pair](https://docs.ca.cryptoprocessing.com/supported-trading-pairs.md), or one of the two currencies isn't enabled for your merchant account. Enable the currency in your [portal](https://docs.ca.cryptoprocessing.com/portal.md#enabling-and-disabling-currencies). |

### Get a fixed exchange quote

`POST /v2/exchange/calculate` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/exchange-calculate.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `sender_currency: The sender currency field is required.` | `sender_currency` is missing, `null` or an empty string. |
| `receiver_currency: The receiver currency field is required.` | `receiver_currency` is missing, `null` or an empty string. |
| `receiver_amount: The receiver amount field is required when the sender amount field is not presented.` | Neither `sender_amount` nor `receiver_amount` was sent. Send one of them. |
| `receiver_amount: The receiver amount field can not be used when the sender amount field is presented.` | Both `sender_amount` and `receiver_amount` were sent. Send only one of them. |
| `receiver_currency: The receiver currency and sender currency must be different.` | `sender_currency` and `receiver_currency` are the same. (The same currency on another network has its own code; see [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md).) |
| `sender_currency: The selected sender currency is invalid.` | The `sender_currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). |
| `receiver_currency: The selected receiver currency is invalid.` | The `receiver_currency` code doesn't exist. |
| `sender_currency: The sender currency must be a string.` | `sender_currency` was sent as another JSON type, such as a number. |
| `receiver_currency: The receiver currency must be a string.` | `receiver_currency` was sent as another JSON type, such as a number. |
| `sender_amount: The sender amount must be a number.` | `sender_amount` isn't a number or a numeric string. |
| `receiver_amount: The receiver amount must be a number.` | `receiver_amount` isn't a number or a numeric string. |
| `sender_amount: The sender amount must be greater than 0.` | `sender_amount` is zero or negative. |
| `receiver_amount: The receiver amount must be greater than 0.` | `receiver_amount` is zero or negative. |
| `sender_amount: The sender_amount must be at least <amount> <currency>` | `sender_amount` is below the minimum for this exchange. `<amount> <currency>` is that minimum, the `min_amount` of `sender_currency` in [/v2/currencies/rates](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md). |
| `receiver_amount: The receiver_amount must be at least <amount> <currency>` | `receiver_amount` is below the minimum for this exchange. `<amount> <currency>` is that minimum, the `min_amount` of `receiver_currency` in [/v2/currencies/rates](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md) for the pair in the opposite direction. |
| `sender_amount: The sender_amount may not be greater than <amount> <currency>` | `sender_amount` is above the maximum for one exchange. `<amount> <currency>` is that maximum. |
| `receiver_amount: The receiver_amount may not be greater than <amount> <currency>` | `receiver_amount` is above the maximum for one exchange. `<amount> <currency>` is that maximum. |
| `sender_amount: We can process only <decimals> decimal places` | `sender_amount` has more decimal places than this currency pair accepts for it. `<decimals>` is the number accepted, for example 2 for a fiat amount. Round `sender_amount` to `<decimals>` decimal places. |
| `receiver_amount: We can process only <decimals> decimal places` | `receiver_amount` has more decimal places than this currency pair accepts for it. `<decimals>` is the number accepted, for example 2 for a fiat amount. Round `receiver_amount` to `<decimals>` decimal places. |
| `sender_amount: Exchange is unavailable for given currencies` | You can't exchange this currency pair: either it isn't a [supported trading pair](https://docs.ca.cryptoprocessing.com/supported-trading-pairs.md), or one of the two currencies isn't enabled for your merchant account. Enable the currency in your [portal](https://docs.ca.cryptoprocessing.com/portal.md#enabling-and-disabling-currencies). |
| `sender_amount: Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.` | The exchange can't be made for this amount at the moment. Try a smaller amount, or try again later. |
| `receiver_amount: Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.` | The exchange can't be made for this amount at the moment. Try a smaller amount, or try again later. |

### Exchange at a fixed rate

`POST /v2/exchange/fixed` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/exchange-fixed.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `price: Fix time is up. Exchange price is changed.` | <ul><li>The quote expired (after its `ts_release`), was already used (including by a request that failed because of insufficient balance), or doesn't match this request: the currencies, the amount field and amount, and `price` exactly as returned. Get a new quote from [/v2/exchange/calculate](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/exchange-calculate.md).</li><li>No quote can exist for the request, for example for an amount below the minimum or above the maximum.</li></ul> |
| `sender_amount: Not enough balance. You have required at least <amount> <currency>` | Your balance in `sender_currency` is lower than this exchange needs. `<amount> <currency>` is the amount needed: the amount exchanged, plus the exchange fee when the fee is charged in `sender_currency`. The quote is used up too: get a new one. |
| `sender_currency: The sender currency field is required.` | `sender_currency` is missing, `null` or an empty string. |
| `receiver_currency: The receiver currency field is required.` | `receiver_currency` is missing, `null` or an empty string. |
| `receiver_amount: The receiver amount field is required when the sender amount field is not presented.` | Neither `sender_amount` nor `receiver_amount` was sent. Send the one the quote was for. |
| `receiver_amount: The receiver amount field can not be used when the sender amount field is presented.` | Both `sender_amount` and `receiver_amount` were sent. Send only the one the quote was for. |
| `foreign_id: The foreign id field is required.` | `foreign_id` is missing, `null` or an empty string. |
| `price: The price field is required.` | `price` is missing or `null`. Send the quote's `price`. |
| `receiver_currency: The receiver currency and sender currency must be different.` | `sender_currency` and `receiver_currency` are the same. (The same currency on another network has its own code; see [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md).) |
| `sender_currency: The selected sender currency is invalid.` | The `sender_currency` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). |
| `receiver_currency: The selected receiver currency is invalid.` | The `receiver_currency` code doesn't exist. |
| `sender_currency: The sender currency must be a string.` | `sender_currency` was sent as another JSON type, such as a number. |
| `sender_amount: The sender amount must be a number.` | `sender_amount` isn't a number or a numeric string. |
| `sender_amount: The sender amount must be greater than 0.` | `sender_amount` is zero or negative. |
| `price: The price must be a number.` | `price` isn't a number or a numeric string. |
| `foreign_id: The foreign id has already been taken.` | The `foreign_id` was already used by one of your exchanges (`/v2/exchange/fixed`, `/v2/exchange/now`) or withdrawals (from any of the three withdrawal endpoints). The check is case-insensitive. Use a new `foreign_id`. |
| `foreign_id: The foreign id may not be greater than 255 characters.` | `foreign_id` is longer than 255 characters. |
| `sender_amount: Exchange is unavailable for given currencies` | You can't exchange this currency pair: either it isn't a [supported trading pair](https://docs.ca.cryptoprocessing.com/supported-trading-pairs.md), or one of the two currencies isn't enabled for your merchant account. Enable the currency in your [portal](https://docs.ca.cryptoprocessing.com/portal.md#enabling-and-disabling-currencies). |

### List supported currencies

`POST /v2/currencies/list` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-list.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `visible: The visible field must be true or false.` | `visible` isn't `true` or `false`. Leave it out to list all supported currencies. |

### Get available currency pairs and exchange rates

`POST /v2/currencies/rates` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/currencies-rates.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `currency_from: The selected currency from is invalid.` | The `currency_from` code doesn't exist. See [API currency codes](https://docs.ca.cryptoprocessing.com/api-reference/currency-codes.md). |
| `currency_to: The selected currency to is invalid.` | The `currency_to` code doesn't exist. |
| `currency_from: The currency from must be a string.` | `currency_from` was sent as another JSON type, such as a number. |
| `currency_to: The currency to must be a string.` | `currency_to` was sent as another JSON type, such as a number. |

### Get transaction details

`GET /v2/transactions/info` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/transactions-info.md)

**400 Bad Request**

| Error message | What it means |
| - | - |
| `id: The id field is required when none of foreign id / txid are present.` | None of `id`, `foreign_id` and `txid` was sent, or each was `null` or an empty string. Send exactly one of them. |
| `foreign_id: The foreign id field is required when none of id / txid are present.` | None of `id`, `foreign_id` and `txid` was sent, or each was `null` or an empty string. Send exactly one of them. |
| `txid: The txid field is required when none of id / foreign id are present.` | None of `id`, `foreign_id` and `txid` was sent, or each was `null` or an empty string. Send exactly one of them. |
| `id: The id must be an integer.` | `id` isn't a whole number. |
| `id: The id must be at least 1.` | `id` is zero or negative. |
| `foreign_id: The foreign id must be a string.` | `foreign_id` was sent as another JSON type, such as a number. |
| `txid: The txid must be a string.` | `txid` was sent as another JSON type, such as a number. |
| `id: The id field is prohibited unless foreign id is in null.` | More than one identifier was sent. Send only one of `id`, `foreign_id` and `txid`. There's one message for each identifier sent, naming another one that was sent, for example `foreign_id: The foreign id field is prohibited unless id is in null.` |

**404 Not Found**

| Error message | What it means |
| - | - |
| `No transaction found.` | <ul><li>None of your transactions matches the identifier.</li><li>The identifier is an invoice's or a payment request's ID or `foreign_id`, or a deposit address's `foreign_id`.</li></ul> |

### List balances

`POST /v2/accounts/list` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/accounts-list.md)

This endpoint has no errors of its own; see [General errors](#general-errors).

### Check API status

`GET /v2/ping` · [Endpoint reference](https://docs.ca.cryptoprocessing.com/api-reference/endpoints/ping.md)

This endpoint has no errors of its own; see [General errors](#general-errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.