Partner API
  1. Integration
Partner API
  • Getting Started
    • Introduction
    • Authentication
    • Business Use Cases
  • API References
    • Partner Operations
      • Get Balances
      • Create Wallet
      • Get Transaction History
      • Retrieve Exchange Rate and Create a Lock
      • Create and Finalize an Exchange
      • Retrieve Detailed Exchange Information
      • Create Crypto Withdrawal
      • Get Crypto Withdrawal Details
      • Create a SEPA Transfer
      • Get SEPA Transfer Details
    • User Accounts
      • Create User Account
      • Add KYC File
      • Add POA File
      • Add User Verification
      • Extend user
      • 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 Information
    • 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
    • Orders
      • Get Rates
      • Retrieve Order Rate and Create a Lock
      • Create and Finalize an Order
      • Get Order Details
    • Payment link
      • Generate Payment Link
      • Get Payment Link Details
  • Integration
    • SDKs & Integration Guides
    • Transaction Processing
    • Error Handling
    • Rate Limiting
    • Webhooks
      • User & KYC Webhooks
        • User Balance Generation Webhook
        • KYC File Added Webhook
        • POA Verification Status Webhook
        • KYC Verification Status Webhook
        • Create Wallet Webhook
      • Transfers & Payments Webhooks
        • P2P Transfer Webhook
        • SEPA Transfer Webhook
        • SEPA Deposit Webhook
        • Crypto Withdrawal Webhook
        • Crypto Deposit Webhook
        • Exchange Webhook
        • Card Transaction Webhook
        • Order status Webhook
        • Payment Link Webhook
      • Card Webhooks
        • Card 3DS Code Webhook
        • Card Activation Code Webhook
  • 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
P403N/AtransferTitle 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 account
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
P458user-already-extendedUser already extended
P459user-not-verifiedUser not verified
P461user-not-extendedUser not extended
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
P460poa-verification-not-foundPOA verification not found. First create verification by extending the user
P462invalid-order-lockOrder lock is not valid or not exist
P463order-not-foundOrder not found
P464payment-link-not-foundPayment link 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