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.

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

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.

⚠️ 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

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.