---
updatedAt: 2025-12-24T11:45:22.000Z
agentTools:
projectIndex: https://devportal.fintensy.com/llms.txt
---
# Error Handling
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
```json
{
"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 |