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

# 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.

## 400 Bad Request

### Request body is invalid JSON

```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`.

### Other endpoint-specific 400 errors

Beyond malformed JSON, several endpoints return `400` for request-level validation failures — missing required fields, invalid field values, or business-rule violations specific to that endpoint (e.g. duplicate `foreign_id`, unsupported currency, amount below the allowed minimum). These use the same `{"error": ..., "code": ...}` shape shown above, with endpoint-specific messages.

<AccordionGroup>
  <Accordion title="/v2/currencies/rates">
    * The selected currency from is invalid.
    * The selected currency to is invalid.

    Endpoint reference: [Get exchange rates](/api-reference/endpoints/currencies-rates)
  </Accordion>

  <Accordion title="/v2/addresses/take">
    * The currency field is required.
    * The foreign id field is required.
    * The selected currency is not enabled for your account.
    * Invalid currency
    * Currency is not allowed without conversion
    * The end user reference must not contain an email address.
    * The selected sender type is invalid.
    * The sender data.first name field is required.
    * The sender data.last name field is required.
    * Address cannot be issued for that end\_user\_reference

    Endpoint reference: [Generate a user deposit address](/api-reference/endpoints/addresses-take)
  </Accordion>

  <Accordion title="/v2/withdrawal/crypto">
    * The currency field is required.
    * Invalid currency
    * The amount must be a number.
    * The amount must not have more than X decimal places.
    * The amount to must be a number.
    * The amount to must not have more than X decimal places.
    * The amount field is required when amount to is not present.
    * The amount field must be greater than 0.
    * The amount to field is required when amount is not present.
    * The amount to field must be greater than 0.
    * The convert to field is required when amount to is present.
    * The foreign id field is required.
    * The foreign id has already been taken.
    * The end user reference must not contain an email address.
    * The selected sender type is invalid.
    * The selected receiver type is invalid.
    * Invalid USDC address
    * The amount must be 5.00000000 USDC.
    * The requested amount exceeds the available balance.
    * Destination tag/memo for currencies that require it.
    * Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.

    Endpoint reference: [Withdraw crypto](/api-reference/endpoints/withdrawal-crypto)
  </Accordion>

  <Accordion title="/v2/crypto/withdrawal_instant">
    * Instant withdrawals are disabled for this merchant.
    * Instant withdrawals are not supported for the specified sender\_currency.
    * The foreign id has already been taken.
    * The sender\_currency field is required.
    * Invalid USDC address
    * The amount must be 5.00000000 USDC.
    * The requested amount exceeds the available balance.
    * The address field is required.
    * The sender\_amount must be greater than 0.

    Endpoint reference: [Withdraw crypto instantly](/api-reference/endpoints/crypto-withdrawal-instant)
  </Accordion>

  <Accordion title="/v2/crypto/withdrawal_instant_exchange">
    * Instant withdrawals are disabled for this merchant.
    * Instant withdrawals are not supported for the specified sender\_currency.
    * The foreign id has already been taken.
    * The sender\_currency field is required.
    * Invalid USDC address
    * The amount must be 5.00000000 USDC.
    * The requested amount exceeds the available balance.
    * Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.
    * The address field is required.
    * The sender\_amount must be greater than 0.

    Endpoint reference: [Withdraw crypto instantly with conversion](/api-reference/endpoints/crypto-withdrawal-instant-exchange)
  </Accordion>

  <Accordion title="/v2/exchange/calculate">
    * The sender currency field is required.
    * The receiver currency field is required.
    * The receiver amount field is required when the sender amount field is not presented.
    * The receiver currency and sender currency must be different.
    * The selected sender currency is invalid.
    * The selected receiver currency is invalid.
    * Invalid amount format
    * The sender amount must be greater than 0.
    * The receiver amount must be greater than 0.
    * The sender\_amount must be at least 2.00000000 ABC
    * The sender\_amount may not be greater than 7.00000000 ABC
    * Exchange is unavailable for given currencies
    * Unable to exchange the requested amount at the moment. Specify a smaller amount or try again later.

    Endpoint reference: [Get a fixed exchange quote](/api-reference/endpoints/exchange-calculate)
  </Accordion>

  <Accordion title="/v2/exchange/fixed">
    * Fix time is up. Exchange price is changed.
    * Insufficient balance. Available: 50.00000000 USDC
    * Currency not supported
    * The amount must be at least 50.00000000 USDC
    * The foreign\_id field is required

    Endpoint reference: [Exchange at a fixed rate](/api-reference/endpoints/exchange-fixed)
  </Accordion>

  <Accordion title="/v2/exchange/now">
    * Exchange rate not available at this time
    * The requested amount exceeds the available balance.
    * Currency not supported
    * The amount must be 5.00000000 USDC
    * The foreign\_id field is required

    Endpoint reference: [Exchange at market rate](/api-reference/endpoints/exchange-now)
  </Accordion>

  <Accordion title="/v2/invoices/create">
    * The foreign id has already been taken.
    * The selected currency is invalid.
    * The amount must be a number.
    * The amount must be 5.00000000 USDC.
    * The email user must be a valid email address.
    * The title field is required.
    * The foreign id field is required.
    * The currency field is required.
    * The amount field is required.
    * The selected type is invalid.
    * Required features \[invoices\_enabled] not enabled.

    Endpoint reference: [Create an invoice](/api-reference/endpoints/invoices-create)
  </Accordion>

  <Accordion title="/v2/invoices/{foreign_id}/cancel">
    * Invoice not found.
    * Invoice cannot be failed in its current state. (invalid\_invoice\_state)
    * Required features \[invoices\_enabled] not enabled.

    Endpoint reference: [Cancel an invoice](/api-reference/endpoints/invoices-cancel)
  </Accordion>

  <Accordion title="/v2/transactions/info">
    * The id field is required when none of foreign id / txid are present.
    * The foreign id field is required when none of id / txid are present.
    * The txid field is required when none of id / foreign id are present.
    * The id must be an integer.

    Endpoint reference: [Get transaction details](/api-reference/endpoints/transactions-info)
  </Accordion>

  <Accordion title="/payments/v1/requests">
    * Payment request with this foreign\_id already exists.
    * user\_fee\_percent must be 0 or 100.

    Endpoint reference: [Create a payment request](/api-reference/endpoints/payments)
  </Accordion>
</AccordionGroup>

## 403 Forbidden

### Signature header does not match the request body

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

The value in `X-Processing-Signature` did not match the request body. See [Authentication](/api-reference/authentication) 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.
* **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.

### Signature header is missing

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

The request does not include the required `X-Processing-Signature` header. Add it with an HMAC-SHA512 signature of the request body.

### API key header does not match your API key

```json theme={null}
{"error":"Bad key header", "code":"bad_header_key"}
```

The value in `X-Processing-Key` did not match any known API key. This can happen for several reasons:

* **Non-whitelisted IP.** If you have configured an IP whitelist in the Merchant Dashboard, requests from any unlisted IP will be rejected. Add the IP to the whitelist, use an already-whitelisted IP, or remove the whitelist entirely.
* **Wrong environment.** Production keys will not work against the sandbox endpoint, and vice versa. Check that the base URL matches the environment your keys belong to.
* **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](/merchant-administration/generate-and-activate-api-keys) for details.

### API key header is missing

```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.
* **Invalid request URL.** Verify the endpoint URL is correct.

### Other endpoint-specific 403 errors

Beyond the header problems above, a few endpoints return `403` for other authorization-related reasons — for example, a feature being disabled for your account.

<AccordionGroup>
  <Accordion title="/v2/withdrawal/crypto">
    * Withdrawal functionality is currently unavailable (withdrawal\_functionality\_unavailable) — see [Enable withdrawals again](/merchant-administration/disable-withdrawals#enable-withdrawals-again)

    Endpoint reference: [Withdraw crypto](/api-reference/endpoints/withdrawal-crypto)
  </Accordion>

  <Accordion title="/v2/crypto/withdrawal_instant">
    * Withdrawal functionality is currently unavailable (withdrawal\_functionality\_unavailable) — see [Enable withdrawals again](/merchant-administration/disable-withdrawals#enable-withdrawals-again)

    Endpoint reference: [Withdraw crypto instantly](/api-reference/endpoints/crypto-withdrawal-instant)
  </Accordion>

  <Accordion title="/v2/crypto/withdrawal_instant_exchange">
    * Withdrawal functionality is currently unavailable (withdrawal\_functionality\_unavailable) — see [Enable withdrawals again](/merchant-administration/disable-withdrawals#enable-withdrawals-again)

    Endpoint reference: [Withdraw crypto instantly with conversion](/api-reference/endpoints/crypto-withdrawal-instant-exchange)
  </Accordion>

  <Accordion title="/payments/v1/requests">
    * Merchant is disabled.

    Endpoint reference: [Create a payment request](/api-reference/endpoints/payments)
  </Accordion>
</AccordionGroup>

## 404 Not Found

`404` is returned when a request references something that doesn't exist — a transaction that can't be found, or a currency that isn't recognized.

<AccordionGroup>
  <Accordion title="/v2/transactions/info">
    * No transaction found.

    Endpoint reference: [Get transaction details](/api-reference/endpoints/transactions-info)
  </Accordion>

  <Accordion title="/payments/v1/requests">
    * The currency.iso is incorrect.
    * payment\_currency.iso is incorrect.

    Endpoint reference: [Create a payment request](/api-reference/endpoints/payments)
  </Accordion>
</AccordionGroup>

## 422 Unprocessable Entity

`422` covers requests that are well-formed and pass basic validation but fail during processing — an internal error while handling the request, a blockchain/infrastructure issue while issuing an address, or (for payment requests) a broader set of business-rule and field-validation checks.

<AccordionGroup>
  <Accordion title="/v2/currencies/rates">
    * Internal error (internal\_error)
    * Something went wrong. Please try later. (internal\_error)
    * Something went wrong. (internal\_error)

    Endpoint reference: [Get exchange rates](/api-reference/endpoints/currencies-rates)
  </Accordion>

  <Accordion title="/v2/addresses/take">
    * Something went wrong, please try again shortly (blockchain\_error)

    Endpoint reference: [Generate a user deposit address](/api-reference/endpoints/addresses-take)
  </Accordion>

  <Accordion title="/v2/withdrawal/crypto">
    * Internal error (internal\_error)
    * Something went wrong. Please try later. (internal\_error)
    * Something went wrong. (internal\_error)

    Endpoint reference: [Withdraw crypto](/api-reference/endpoints/withdrawal-crypto)
  </Accordion>

  <Accordion title="/v2/exchange/calculate">
    * Internal error (internal\_error)
    * Something went wrong. Please try later. (internal\_error)
    * Something went wrong. (internal\_error)

    Endpoint reference: [Get a fixed exchange quote](/api-reference/endpoints/exchange-calculate)
  </Accordion>

  <Accordion title="/payments/v1/requests">
    * The iso is a mandatory field.
    * The currency.iso is disabled.
    * The currency.network\_name field is mandatory for crypto currencies.
    * The combination of currency and network is not supported.
    * The amount field is mandatory.
    * The minimum amount is \<amount> EUR.
    * The maximum amount is \<amount> EUR.
    * The amount for \<currency> cannot have more than \<decimal-places> decimal places.
    * It is obligatory - to fill in life\_time\_date\_time or life\_time\_duration.
    * Only one of fields life\_time\_date\_time and life\_time\_duration should be field.
    * The lifespan must be longer than or equal to \<span> {minutes/days}.
    * The lifespan must be shorter than or equal \<span> {minutes/days}.
    * The email address is incorrect.
    * payment\_currency must not be empty if provided.
    * payment\_currency.iso must be a cryptocurrency.
    * payment\_currency.iso must not be empty if provided.
    * payment\_currency.iso is disabled.
    * Exchange rate is not available between \<currency.iso> and \<payment\_currency.iso>.
    * payment\_currency.network\_name must not be empty if provided.
    * payment\_currency.network\_name cannot be specified without payment\_currency.iso.
    * The description must be 255 characters or less.
    * The description must not be empty if provided.
    * Foreign ID must be 255 characters or less.
    * The foreign\_id must not be empty if provided.
    * The url\_store is invalid.
    * The url\_store must be 255 characters or less.
    * The url\_success is invalid.
    * The url\_success must be 255 characters or less.
    * The url\_failed is invalid.
    * The url\_failed must be 255 characters or less.
    * The end\_user\_reference must not be empty if provided.
    * The end\_user\_reference must be 255 characters or less.
    * The rate\_mode must be either standard or fixed.
    * The sender\_type field must be provided when sender\_data is present.
    * The sender\_type must be either ‘natural’ or ‘legal’.
    * The sender\_data object must be provided when sender\_type is present.
    * The sender\_data must be a valid object.
    * The first\_name must be provided for sender\_type = natural.
    * The first\_name must be 255 characters or less.
    * The last\_name must be provided for sender\_type = natural.
    * The last\_name must be 255 characters or less.
    * The date\_of\_birth must be in YYYY-MM-DD format.
    * The legal\_name must be provided for sender\_type = legal.
    * The legal\_name must be 255 characters or less.
    * The country\_of\_registration must be provided for sender\_type = legal.
    * The country\_of\_registration must contain exactly 3 characters.
    * The country\_of\_registration must be a valid ISO Alpha-3 code.

    Endpoint reference: [Create a payment request](/api-reference/endpoints/payments)
  </Accordion>
</AccordionGroup>