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": "P4102",
  "errorName": "insufficient-funds",
  "errorMessage": "Insufficient funds"
}

errorCode: A unique code such as P4101 or P4102 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 primary signal that the request failed.

Use errorCode for Logic:

Treat P403 as a general request validation failure.

For specific codes such as P4102 (insufficient-funds) or P4103 (invalid-lock), implement targeted application logic.

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 avoid displaying raw technical errors directly to end users.

Common Error Codes Reference

The tables below provide the complete reference of errors returned by the system.

HTTP 400 / Business Logic Errors

Error Code	Error Name	Error Message Example	Description
`P403`	Validation Error	`currency must be one of the following values...`	Request body failed schema/format validation.
`P4102`	`insufficient-funds`	`Insufficient funds`	Account balance is too low to complete the operation.
`P4103`	`invalid-lock`	`Lock is not valid or not exist`	Provided processing lock is invalid or has expired.

HTTP 401 - Unauthorized Errors

Response	Description
`Access Denied. xo1`	API key not provided in request headers.
`Access Denied. xo2`	Invalid API key provided.
`Access Denied. xo3`	Request IP address is not whitelisted.

HTTP 404 - Not Found Errors

Error Code	Error Name	Error Message Example	Description
`P4001`	`partner-not-found`	`Partner not found`	The specified partner account does not exist.
`P4002`	`partner-config-not-found`	`Partner config not found`	Configuration settings for the partner are missing.
`P4101`	`transaction-not-found`	`Transaction not found`	Requested transaction ID could not be found.

HTTP 500 - Server Errors

Error Code	Error Name	Error Message Example	Description
`P5000`	`unknown-exception`	`Please contact us`	An unexpected internal server error occurred.

1. Standard API Errors (Business Logic)#

2. Validation Errors (P403)#

Key Characteristics#

Best Practices for Error Handling#

Common Error Codes Reference#

HTTP 400 / Business Logic Errors#

HTTP 401 - Unauthorized Errors#

HTTP 404 - Not Found Errors#

HTTP 500 - Server Errors#