1. Integration
Partner API
  • Getting Started
    • Introduction
    • Authentication
    • Business Use Cases
  • API References
    • Balances & History
      • Get Balances
      • Get Balance History
    • Crypto Deposits
      • Get Crypto Deposit Details
      • Add Travel Rule
    • Crypto Withdrawals
      • Get Whitelisted Wallets
      • Add Whitelisted Wallet
      • Delete Whitelisted Wallet
      • Create Crypto Withdrawal
      • Get Crypto Withdrawal Details
    • SEPA Deposits
      • Get SEPA Payment Details
      • Get SEPA Deposit Details
    • SEPA Withdrawals
      • Create SEPA Withdrawal
      • Get SEPA Withdrawal Details
    • Currency Exchange
      • Get Rates
      • Create Lock
      • Create Exchange
      • Get Exchange Details
  • Integration
    • Integration Guides
    • Transaction Processing
    • Error Handling
    • Rate Limiting
    • Webhooks
      • Crypto Deposit Webhook
      • Crypto Withdrawal Webhook
      • SEPA Deposit Webhook
      • SEPA Withdrawal Webhook
      • Exchange Webhook
  • Reference
    • Supported Currencies
    • Fees
    • FAQ
    • Changelog
    • Support
  1. Integration

Error Handling

This page explains the error response model used across the Fintegence Partner API and lists all error codes. Understanding them is essential for building a robust integration.

Error Response Format#

All errors use the same three-field structure:
{
  "errorCode": "P4103",
  "errorName": "insufficient-funds",
  "errorMessage": "Insufficient funds"
}
errorCode - a stable code, e.g. P4103. Use it to drive your application logic.
errorName - a stable, readable identifier of the error type.
errorMessage - a description intended for debugging, logging and support analysis. Do not rely on its exact wording in your code.

Validation Errors (P4007)#

P4007 is returned with HTTP 400 when the request fails format or schema validation - for example a missing required field, an invalid enum value, a wrong format or a value out of range.
{
  "errorCode": "P4007",
  "errorName": "validation-error",
  "errorMessage": "walletType must be one of the following values: SELF_CUSTODY, CUSTODIAL"
}
The errorMessage may contain several validation problems in one string, separated by commas. For the full validation rules, see the schema of the endpoint.

Best Practices#

1.
Check the HTTP status code first - it tells you whether the request failed and which category the error belongs to.
2.
Use errorCode for logic - treat P4007 as a general validation failure, and implement targeted handling for specific codes such as P4103 (insufficient funds) or P4201 (invalid lock).
3.
Log errorMessage - always log the full message for debugging, but do not display raw technical messages to end users.
4.
Retry only server errors - 4xx errors will not succeed when repeated without changes. For 500, retry later - but for withdrawals and exchanges, first check whether the transaction was created (see Transaction Processing).

Error Codes Reference#

400 - Bad Request#

Error CodeError NameError Message ExampleWhen it occurs
P4007validation-erroramount must be a positive numeric stringThe request failed format or schema validation.
P4103insufficient-fundsInsufficient fundsThe balance is too low for the withdrawal or exchange.
P4104amount-below-minimumAmount below minimumThe amount is lower than withdrawal.minAmount or exchange.minAmount in Get Balances.
P4105amount-precision-exceededAmount has too many decimal places for this currencyThe amount has more decimal places than the precision of the currency.
P4201invalid-lockLock is not valid or not existThe lock does not exist, has expired or has already been used. Create a new lock.
P4202invalid-exchange-pairExchange is only allowed between EUR and a cryptocurrencyThe exchange is not between EUR and a cryptocurrency.
P4301wallet-address-not-validWallet address not validThe wallet address is not valid for the given network.
P4302wallet-address-already-whitelistedWallet address already whitelistedThe address (with the same memo) is already on the whitelist.
P4303wallet-address-not-whitelistedWallet address not whitelistedThe walletId does not exist on your whitelist or has been removed.
P4304ownership-declaration-requiredOwnership declaration must be confirmed when owner type is SENDERownerType is SENDER and ownershipDeclaration is not true.
P4305travel-rule-data-already-addedTravel rule data already added for this wallet addressTravel Rule information has already been provided for this address. To correct it, contact support.

401 - Unauthorized#

Error CodeError NameError Message ExampleWhen it occurs
P4001missing-api-keyAPI key is missingThe x-api-key header is missing.
P4002invalid-api-keyAPI key is invalidThe API key is invalid or belongs to the other environment.

403 - Forbidden#

Error CodeError NameError Message ExampleWhen it occurs
P4003ip-not-allowedRequest from this IP address is not allowedThe request comes from an IP address that is not whitelisted for your account.
P4004access-deniedAccess denied, you do not have permission for this actionYour account does not have permission for this action.

404 - Not Found#

Error CodeError NameError Message ExampleWhen it occurs
P4101balance-not-foundBalance not foundThe balance does not exist or does not belong to your account.
P4102transaction-not-foundTransaction not foundThe transaction does not exist, does not belong to your account or is of a different type than the endpoint.
P4306whitelisted-wallet-address-not-foundWhitelisted wallet address not foundThe whitelisted wallet does not exist or has already been removed.

500 - Server Error#

Error CodeError NameError Message ExampleWhen it occurs
P5000unknown-errorPlease contact usAn unexpected server error. Retry later. If the problem persists, contact support@fintegence.com.
Previous
Transaction Processing
Next
Rate Limiting
Built with