Documentation

Possible errors

How the API reports errors and how to handle them.

Errors are returned as JSON. Identify the error by the HTTP status together with error.code. The message field is for display and is localized by accept-language — do not rely on its text in code.

Error format

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "string",
    "kind": "field",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "rule": "string"
      }
    ],
    "details": {},
    "requestId": "4ad561fd-6ecd-445d-a65f-989ea5995f18",
    "timestamp": "2026-10-05T12:08:14.331Z",
    "path": "/api/v1/invoices"
  }
}

HTTP statuses and codes

HTTPCodeDescription
400VALIDATION_FAILEDRequest parameters failed validation.
400INVALID_JSONInvalid JSON in the request body.
400QUERY_TOO_COMPLEXThe query is too complex.
400PROJECT_DELETEDThe project is deleted.
400INVOICE_ADDRESS_GENERATION_FAILEDFailed to generate the invoice address.
400INVOICE_COIN_UNAVAILABLEThe coin is not available for invoices.
400INVOICE_CANCELLATION_NOT_ALLOWEDThe invoice cannot be cancelled.
400INVOICE_DESCRIPTION_INVALIDInvalid invoice description.
400INVOICE_AMOUNT_INVALIDInvalid invoice amount.
400INVOICE_AMOUNT_BELOW_MINIMUMThe amount is below the minimum.
400INVOICE_AMOUNT_ABOVE_MAXIMUMThe amount is above the maximum.
400INVOICE_RATE_UNAVAILABLENo rate available for the coin.
400PROJECT_STATIC_WALLET_INVALIDInvalid static wallet.
400PROJECT_STATIC_WALLET_ASSET_UNAVAILABLEThe asset is not available for static wallets.
400PROJECT_STATIC_WALLET_LIMIT_EXCEEDEDStatic wallet limit exceeded.
400PROJECT_ACCEPTED_COINS_UNAVAILABLEProject coins are unavailable.
400PROJECT_DEPOSIT_ASSET_UNAVAILABLEThe deposit asset is unavailable.
400WITHDRAWAL_ASSET_UNAVAILABLEThe withdrawal asset is unavailable.
400WITHDRAWAL_DESTINATION_INVALIDInvalid destination address.
400WITHDRAWAL_AMOUNT_INVALIDInvalid withdrawal amount.
400WITHDRAWAL_AMOUNT_BELOW_MINIMUMThe withdrawal is below the minimum.
400WITHDRAWAL_BALANCE_INSUFFICIENTInsufficient balance.
400WITHDRAWAL_QUOTE_INVALID_OR_EXPIREDThe quote is invalid or expired.
400WITHDRAWAL_QUOTE_MISMATCHWithdrawal parameters do not match the quote.
400WITHDRAWAL_QUOTE_ALREADY_USEDThe quote is already used.
401MERCHANT_AUTH_REQUIREDValid API key authorization is required.
403ACCOUNT_ACCESS_DENIEDAccess to the operation is denied.
404PROJECT_NOT_FOUNDProject not found.
404INVOICE_NOT_FOUNDInvoice not found.
404PAYMENT_TRANSACTION_NOT_FOUNDTransaction not found.
404PROJECT_STATIC_WALLET_NOT_FOUNDStatic wallet not found.
404TOKEN_TARIFF_NOT_FOUNDToken tariff not found.
404WITHDRAWAL_NOT_FOUNDWithdrawal not found.
409INVOICE_EXTERNAL_ID_CONFLICTorderId is already used with different invoice parameters.
409PROJECT_STATIC_WALLET_EXTERNAL_ID_CONFLICTorderId is already used with different wallet parameters.
413PAYLOAD_TOO_LARGEThe request is too large.
429INVOICE_CREATION_RATE_LIMITEDInvoice creation rate limit exceeded.
429PROJECT_STATIC_WALLET_CREATION_RATE_LIMITEDStatic wallet creation rate limit exceeded.
500INTERNAL_SERVER_ERRORInternal server error. The result of the original POST request may be unknown.
503PROJECT_DEPOSIT_ADDRESS_UNAVAILABLEThe deposit address is temporarily unavailable.
503PROJECT_WALLET_GENERATION_FAILEDFailed to generate the project wallet.

Handling errors

  • Combine the HTTP status with error.code: for example, 400 + INVOICE_AMOUNT_BELOW_MINIMUM clearly means the invoice amount is too small.
  • For 409, check the conflicting parameters.
  • For 429, retry only after a delay.
  • Keep the requestId from the response and send it to support together with the HTTP status and error.code.
{
  "error": {
    "requestId": "4ad561fd-6ecd-445d-a65f-989ea5995f18"
  }
}
← PreviousStatusesNext →Project cryptocurrencies