Our APIs use a layered error model to provide clear, actionable feedback while keeping error handling consistent across all endpoints and services.

Errors are exposed at three levels of detail.

1. HTTP Status Codes

At the highest level, the API relies on standard HTTP status codes to describe the outcome of a request.

HTTP Status	Meaning	Description
`200 OK`	Success	The request was successfully processed.
`400 Bad Request`	Client error	The request is syntactically valid but contains invalid or inconsistent data.
`401 Unauthorized`	Authentication error	Authentication failed or is missing.
`404 Not Found`	Resource error	The requested resource does not exist or is not accessible.
`500 Internal Server Error`	Server error	An unexpected error occurred on the server side.

Note
Additional error details are only provided for 400 Bad Request responses.

2. Functional Error Codes (Level 2)

When a request fails with 400 Bad Request, the response body contains a functional error object describing the high-level cause of the failure.

Response Structure

{
  "code": "10000101",
  "message": "Validation error occurred",
  "errors": [
    {
      "field": "branch_external_reference",
      "actual_value": "999983",
      "code": "4004",
      "min_length": null,
      "max_length": null
    }
  ]
}

Fields Description

Field	Type	Description
`code`	string	Internal functional error code identifying the global error type.
`message`	string	Human-readable description of the error.
`errors`	array	List of detailed validation errors (Level 3).

The top-level code identifies the general failure category (for example validation, consistency, or business rules).

Internal Functional Error Codes

The following table describes the internal functional error codes returned at the top level of a 400 Bad Request response. These codes indicate the general category of the failure, but do not provide field-level validation details.

Internal Code	Message	Description
`10000101`	Wrong Input	One or more input values are invalid.
`10000102`	Missing Input	One or more required input parameters are missing from the request.
`10000103`	No HTTPS	The request was not sent over HTTPS. Only secure HTTPS requests are allowed.
`10000104`	Invalid Operation	The requested operation is not allowed in the current context or resource state.
`10000105`	Invalid Bank Credentials	The provided bank credentials are invalid or rejected by the banking provider.
`10000106`	Expired	The request references an expired resource, token, or context.
`10000601`	Batch Issue	An error occurred during batch or asynchronous processing.
`10001002`	Missing Email For Signer	A signer does not have an email address, which is required to proceed.
`10001003`	Entity Already Exists	The entity being created already exists and cannot be created again.

⚠️ Important
These internal error codes only describe the global error category.
To identify which input is invalid and why, always rely on the code field inside the errors object, which provides detailed, field-level validation information.

3. Field-Level Validation Errors (Level 3)

The errors array provides fine-grained validation details when the failure is caused by incorrect input data.

Each object in the errors array refers to one specific input field.

Validation Error Object

Field	Type	Description
`field`	string	Name of the input field that caused the error.
`actual_value`	string / number	Value received by the API.
`code`	string	Validation error code identifying the rule that was violated.
`min_length`	number \| null	Minimum accepted value (when applicable).
`max_length`	number \| null	Maximum accepted value (when applicable).

This structure allows API consumers to:

Identify which field is invalid
Understand why it is invalid
Know which constraints must be respected

Validation Error Codes

Validation error codes are standardized and reused across all APIs.
They describe the exact validation rule that failed.

Code	Meaning
`4001`	Empty
`4002`	Incorrect length
`4003`	Invalid format
`4004`	Incorrect value
`4005`	Wrong email format
`4006`	Greater than
`4007`	Greater than or equal
`4008`	Incorrect date
`4009`	Passwords do not match
`4010`	Incorrect password pattern
`4011`	Smaller than
`4012`	Smaller than or equal
`4013`	Date must be in the future
`4014`	Date must be in the past
`4015`	Invalid credit amount
`4016`	Value must be unique
`4017`	National identification number does not match date of birth
`4018`	Invalid APR rate
`4019`	Missing required elements
`4020`	Obsolete elements
`4021`	Expired code
`4022`	Code already requested
`4023`	Too many codes requested for user