Error Handling

This page explains the error response model used across the Fintegence Partner API. Understanding the main error categories and how to react to them is essential for building a robust integration.

1. Standard API Errors (Business Logic)

These errors relate to business logic, resource state, or permissions, and they use a consistent three-field structure.

Example:

{
  "errorCode": "P424",
  "errorName": "source-or-destination-required",
  "errorMessage": "Source or destination must be provided."
}

errorCode: A unique code such as P424 or P433 that can be used to drive application logic.

errorName: A readable identifier for the error type.

errorMessage: A detailed description intended for debugging, logging, and support analysis.

2. Validation Errors (`P403`)

These errors are generated when the request payload fails format or schema validation, for example because of a missing required field, invalid enum value, or wrong value format.

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: Validation failures always return errorCode: "P403".

No errorName: Validation errors omit the errorName field.

Concatenated Messages: The errorMessage field may contain multiple validation failures combined into a single string.

HTTP 400: These responses always return 400 Bad Request.

P403 Note

P403 is an aggregate validation error code. The errorMessage field may include multiple failed conditions in one response, such as invalid format, missing required values, or unsupported field content. For the full set of validation rules, refer to the relevant endpoint schema.

Best Practices for Error Handling

Regardless of error type, a resilient integration should follow the same general approach.

Check the HTTP Status Code First: Use the HTTP status code as the first signal that the request failed.

Use errorCode for Logic:

Treat P403 as a general validation failure.

For other codes such as P424 or P433, implement specific handling where needed.

Use errorName for Readable Classification: When present, errorName is a stable and readable identifier for application-level handling and diagnostics.

Log errorMessage for Debugging: Always log the full errorMessage, but do not display raw technical errors directly to end users.

Common Error Codes Reference

The tables below focus on commonly encountered or operationally important errors.

HTTP 400 - Bad Request Errors (Common)

Error Code	Error Name	Error Message Example
`P403`	Validation Error	`currency must be one of the following values...`
`P410`	`invalid-currency`	Currency not found
`P411`	`user-exists`	User exists
`P412`	`invalid-user`	User does not exist
`P424`	`source-or-destination-required`	Source or destination must be provided.
`P433`	`insufficient-funds`	Insufficient funds
`P451`	`forbidden-country-card`	User of this country cannot have card
`P455`	`user-suspended`	User suspended

HTTP 401 - Unauthorized Errors

Response	Description
`Access Denied. xo1`	API key not provided
`Access Denied. xo2`	Invalid API key provided
`Access Denied. xo3`	IP address not whitelisted (production)

HTTP 404 - Not Found Errors (Common)

Error Code	Error Name	Error Message Example
`P421`	`withdrawal-not-found`	Withdrawal not found
`P423`	`transfer-not-found`	Transfer not found
`P425`	`exchange-not-found`	Exchange not found
`P463`	`order-not-found`	Order not found
`P464`	`payment-link-not-found`	Payment link not found

HTTP 202 - Accepted / Pending Responses

Error Code	Error Name	Error Message Example
`P210`	`poa-file-not-found`	POA file not yet uploaded.
`P211`	`poa-verification-pending`	POA verification pending
`P212`	`kyc-verification-pending`	KYC verification pending

1. Standard API Errors (Business Logic)#

2. Validation Errors (P403)#

Key Characteristics#

Best Practices for Error Handling#

Common Error Codes Reference#

HTTP 400 - Bad Request Errors (Common)#

HTTP 401 - Unauthorized Errors#

HTTP 404 - Not Found Errors (Common)#

HTTP 202 - Accepted / Pending Responses#