Partner API
  1. Integration
Partner API
  • Getting Started
    • Introduction
    • Authentication
    • Business Use Cases
  • API References
    • Partner Operations
      • Get Balances
      • Get Transaction History
      • Retrieve Exchange Rate and Create a Lock
      • Create and Finalize an Exchange
      • Create Crypto Withdrawal
      • Create a SEPA Transfer
      • Get SEPA Transfer Details
    • User Accounts with KYC
      • Create User Account and Generate Balances
      • Add KYC File
      • Add POA File
      • Add User Verification
      • Update Existing User
      • Delete User
      • Suspend User
      • Unsuspend User
      • Get User Balances
      • Get User Transaction History
    • User Accounts without KYC
      • Create User Account and Generate Balances Without KYC
      • Update Existing User
      • Delete User
      • Suspend User
      • Unsuspend User
      • Get User Balances
      • Get User Transaction History
    • KYC by P100
      • Creating KYC Verification
      • Redirect to Verification
      • Get KYC Status
    • Currency Exchange
      • Retrieve Exchange Rate
      • Retrieve Exchange Rate and Create a Lock
      • Create and Finalize an Exchange
      • Retrieve Detailed Exchange Infromation
    • Crypto Deposits
      • Update Travel Rule
    • Crypto Withdrawals
      • Get Network Fee
      • Create Crypto Withdrawal
      • Get Crypto Withdrawal Details
    • Internal Transfers
      • Create a Transfer
      • Get Transfer Details
    • Virtual Cards
      • Create Virtual Card
      • Get All User Cards
      • Get Card Details
      • Update Card PIN
      • Block Card
      • Unblock Card
      • Get Card Limits
      • Update Card Limits
      • Delete Card
    • Custom Fiat Operations
      • SEPA Deposit & Withdrawal
  • Integration
    • SDKs & Integration Guides
    • Transaction Processing
    • Error Handling
    • Rate Limiting
    • Webhooks
      • User & KYC Webhooks
        • User Balance Generation
        • KYC File Added
        • POA Verification Status
        • KYC Verification Status
      • Transfers & Payments Webhooks
        • P2P Transfer Webhook
        • SEPA Transfer
        • SEPA Deposit
        • Crypto Withdrawal
        • Crypto Deposit
        • Exchange
        • Card Transaction
      • Card Webhooks
        • Card 3DS Code
        • Card Activation Code
  • Reference
    • Supported Countries
    • Supported Currencies
    • Fees
    • FAQ
    • Changelog
    • Support
  1. Integration

Error Handling

The P100 API uses a consistent JSON structure for error responses. Understanding the two primary types of errors is key to building a robust integration.

Error Response Structure#

You will encounter two types of error structures depending on the nature of the issue: standard API errors and data validation errors.

1. Standard API Errors (Business Logic)#

These errors relate to business logic, resource states, or permissions.
They always feature a three-field structure.
Example (``):
{
  "errorCode": "P424",
  "errorName": "source-or-destination-required",
  "errorMessage": "Source or destination must be provided."
}
errorCode: A unique code (P424, P433, etc.) for driving application logic.
errorName: A human-readable identifier for the error.
errorMessage: A detailed description for debugging and logging purposes.

2. Validation Errors (P403)#

These errors are automatically generated when request data fails format validation (e.g., invalid email format, missing required field).
They have a streamlined structure.
Example (``):
{
  "errorCode": "P403",
  "errorMessage": "currency must be one of the following values: btc, eth, usdt. Amount can have at most 8 decimal places."
}
Key Characteristics:
Fixed Error Code: Always returns errorCode: "P403".
errorName is Omitted: This field is not included.
Concatenated Messages: errorMessage may contain multiple validation failures in a single string.
Always a 400 Status: The response will always have HTTP 400 Bad Request.

Best Practices for Error Handling#

Regardless of the error type, follow this unified approach:
1.
Check the HTTP Status Code First
Use the status code (4xx or 5xx) as the initial indicator of an error.
2.
Use errorCode for Logic
If errorCode is P403, handle it as a general validation failure (e.g., display an "invalid input" message).
For all other codes (P424, P433, etc.), trigger specific logic (e.g., "Insufficient funds").
3.
Log errorMessage for Debugging
Always log the full errorMessage to aid in diagnosing issues,
but do not display it to the end-user.

Complete Error Code Reference#

The following sections contain all possible error codes returned by the P100 API, organized by HTTP status code for easy reference.

HTTP: 400 - Bad Request Errors#

Error CodeError NameError Message
P403transferTitle should not be empty
P410invalid-currencyCurrency not found
P411user-existsUser exists
P412invalid-userUser does not exist
P424source-or-destination-requiredSource or destination must be provided.
P426invalid-file-typeFile type is not supported. Allowed types: image/jpeg, image/png, image/jpg
P429user-balance-exceeds-limit-exceptionUser has balance greater than {amount} EUR
P430maximum-number-of-verificationsUser has maximum number of verifications
P431forbidden-countryUser of this country cannot have iban.
P432invalid-exchange-lockExchange lock is not valid or not exist.
P433Insufficient fundsinsufficient-funds
P434invalid-cardCard does not exist
P435invalid-dateInvalid date. Date must be between {year} and {year}
P436requirements-not-foundRequirements not found.
P437must-be-ownerUser must be the owner of the wallet
P439no-kyc-filesNo kyc files to add
P440file-too-largeFile is too large
P442user-already-verifiedUser already verified
P444poa-verification-rejectedPOA verification rejected
P446kyc-verification-is-not-valid-or-has-expiredKYC verification is not valid or has expired
P447poa-already-verifiedPOA already verified
P450KYC already verifiedkyc-already-verified
P451forbidden-country-cardUser of this country cannot have card
P452country-change-not-possibleChanging country not possible - contact us
P453too-many-kyc-verification-retiresVerification process has been started too many times
P454suspend-user-impossibleUser has active cards and suspension is not possible
P455user-suspendedUser suspended
P457currencies-cannot-be-the-samecurrencyFrom and currencyTo cannot be the same
P500unknown-exceptionPlease contact P100
P501service-temporarily-unavailableService temporarily unavailable
P403 – An aggregate validation error code (HTTP 400). The errorMessage field may contain multiple, concatenated messages about various failed conditions (e.g., invalid data format, missing field).

HTTP: 401 - Unauthorized#

ResponseDescription
Access Denied. xo1API key not provided
Access Denied. xo2Invalid API key provided
Access Denied. xo3IP address not whitelisted (production only)

HTTP: 404 - Not Found Errors#

Error CodeError NameError Message
P421withdrawal-not-foundWithdrawal not found
P423transfer-not-foundTransfer not found
P425exchange-not-foundExchange not found
P427kyc-file-not-foundKyc file not found. Missing files: [varies]
P428sepa-transfer-not-foundSepa transfer not found
P445kyc-verification-not-foundKYC verification not found
P427 – This error indicates that one or more required KYC files are missing. The error message will specify which of the following files are absent: FRONT PHOTO OF DOCUMENT, FACE PHOTO, and/or BACK PHOTO.

HTTP: 202 - Accepted (Pending Responses)#

Error CodeError NameError Message
P210poa-file-not-foundPOA file not yet uploaded. Verification is pending and will resume after POA is added
P211poa-verification-pendingPOA verification pending
P212kyc-verification-pendingKYC verification pending

Need Help?#

📖 FAQ
Find answers to the most common questions about our API.
💬 Support
Can't find what you're looking for? Contact our support team for assistance.
Previous
Transaction Processing
Next
Rate Limiting
Built with