Error handling

When integrating with Lerian APIs, robust error handling is essential for a seamless user experience and resilient application performance. This guide explains how errors are structured, how to classify them, and how to respond to different error categories.

Error response model

All Lerian APIs return a structured error object for every error. The format is consistent across all services:

{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}

Field definitions:

code: A unique, stable identifier for the error. Use this field for programmatic error handling.
title: A brief summary of the issue.
message: Detailed, human-readable guidance for resolving the error.

Always use the code field to identify errors programmatically. Titles and messages may evolve to improve clarity, but error codes remain stable.

Field-level error details

When an error relates to specific fields in the request payload, the response includes a fields object with granular details:

{
   "code": "CRM-0003",
   "title": "Missing Fields in Request",
   "message": "Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.",
   "fields": {
      "document": "document is a required field"
   }
}

{
   "code": "CRM-0047",
   "title": "Bad Request",
   "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
   "fields": {
      "legalName": "legalName is a required field.",
      "parentOrganizationId": "parentOrganizationId must be a valid UUID"
   }
}

{
   "code": "CRM-0053",
   "title": "Unexpected Fields in the Request",
   "message": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
   "fields": {
      "extraField": "extraField is not allowed"
   }
}

Error code structure

Every error code follows a standardized format that identifies both the service and the specific error:

<PREFIX>-<NNNN>

PREFIX (3 letters): Identifies the service or plugin that produced the error.
NNNN (4 digits): A unique number within that service.

Service prefixes

Prefix	Service
AUT	Access Manager (authentication)
IDE	Access Manager (identity)
CRM	CRM
FEE	Fees Engine
Pix	Pix
BTF	Bank Transfer (TED)
TPL	Reporter
TRC	Tracer

Midaz core uses numeric-only codes (e.g., 0002, 0009) without a prefix. All other services include their 3-letter prefix.

Number ranges

Error codes are organized into ranges that indicate the error’s origin:

Range	Category	Description
`0001`–`0099`	System and middleware	Authentication, authorization, headers, rate limiting
`0100`–`0999`	Service-specific	Validation, business logic, and domain errors within the plugin
`1000`–`1999`	External integration	Errors originating from external providers or upstream services

This structure allows you to quickly identify whether an error comes from your request (low numbers), the service’s business logic (mid-range), or an external dependency (1000+).

Error classification

Understanding the type of error helps you decide how to respond. Lerian errors fall into three categories:

Validation errors

Errors caused by incorrect or missing input in the request. Characteristics:

HTTP status 400 (Bad Request)
Include a fields object when specific fields are at fault
Always preventable by validating input before sending

Examples: Missing required fields, invalid UUIDs, unsupported enum values, fields exceeding maximum length. What to do: Check the fields object for specifics. Correct the input and retry.

Business logic errors

Errors caused by operations that violate domain rules or resource state constraints. Characteristics:

HTTP status 404 (Not Found), 409 (Conflict), or 422 (Unprocessable Entity)
Indicate that the request is syntactically valid but cannot be processed

Examples: Resource not found, duplicate name conflicts, invalid status transitions (e.g., activating an already active rule), insufficient balance. What to do: Verify the resource exists and is in the expected state. Check the error message for the specific constraint that was violated.

System errors

Errors caused by infrastructure issues, timeouts, or unexpected failures. Characteristics:

HTTP status 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), or 504 (Gateway Timeout)
Not caused by your input — the same request may succeed later

Examples: Internal server error, service temporarily unavailable, gateway timeout. What to do: Retry with exponential backoff (see guidance below). If the error persists, contact support.

HTTP status codes

Lerian APIs use a focused set of HTTP status codes:

Code	Meaning	Category
`400`	Bad Request	Validation error — fix the request
`401`	Unauthorized	Missing or invalid authentication credentials
`403`	Forbidden	Valid credentials but insufficient permissions
`404`	Not Found	The requested resource does not exist
`409`	Conflict	The operation conflicts with the current resource state
`422`	Unprocessable Entity	Valid syntax but violates business rules
`429`	Too Many Requests	Rate limit exceeded — wait and retry
`500`	Internal Server Error	Unexpected server failure — retry later
`502`	Bad Gateway	Upstream service returned an invalid response
`503`	Service Unavailable	Service temporarily unavailable — retry later
`504`	Gateway Timeout	Request timed out — retry later

Retry guidance

Not all errors should be retried. The following table helps you decide:

Error type	Retryable	Recommended action
`400` validation errors	No	Fix the request payload
`401` / `403` auth errors	No	Check credentials and permissions
`404` not found	No	Verify the resource ID
`409` conflicts	Sometimes	Check current state, then retry if the conflict is resolved
`422` business logic	No	Adjust the operation to comply with business rules
`429` rate limit	Yes	Wait for the retry window, then retry
`500` internal errors	Yes	Retry with exponential backoff
`502` / `503` / `504`	Yes	Retry with exponential backoff

Exponential backoff strategy

For retryable errors, use exponential backoff to avoid overwhelming the service:

First retry: Wait 1 second
Second retry: Wait 2 seconds
Third retry: Wait 4 seconds
Maximum retries: Stop after 3–5 attempts
Jitter: Add a small random delay (0–500ms) to each wait to prevent thundering herd

Never retry 400, 401, 403, or 422 errors automatically. These indicate issues with your request that must be fixed before retrying.

Troubleshooting by category

Missing or invalid fields (400)

Most 400 errors include a fields object that tells you exactly which fields need attention. Common causes:

Required field omitted from the request body
Field value does not match the expected type (e.g., string instead of UUID)
Field value exceeds maximum length
Unexpected extra fields in the request body

Resolution steps:

Read the fields object in the error response
Compare your request against the API reference for that endpoint
Verify field names use lowerCamelCase (not snake_case)
Verify dates use ISO 8601 format with Z suffix
Verify UUIDs are valid v4 format

Authentication and authorization (401/403)

Common causes:

Missing Authorization header
Expired or revoked token
Token does not grant access to the requested endpoint

Resolution steps:

Confirm that Access Manager is enabled in your environment
Verify the token is present in the Authorization header
Request a new token if the current one has expired
Check that the token’s scope includes the required permissions

Resource not found (404)

Common causes:

Incorrect resource ID in the URL path
Resource was soft-deleted
Resource belongs to a different organization or ledger

Resolution steps:

Verify the ID format (must be a valid UUID)
List resources to confirm the ID exists
Check that you are using the correct organizationId and ledgerId path parameters

Conflict errors (409)

Common causes:

Creating a resource with a name that already exists (e.g., duplicate ledger name, duplicate rule name)
Attempting an operation that has already been completed (e.g., duplicate transaction)

Resolution steps:

Read the error message to identify which field caused the conflict
Use a different value (e.g., rename) or retrieve the existing resource instead
For idempotent operations, verify the existing resource matches your intent

Rate limiting (429)

Common causes:

Too many requests in a short period

Resolution steps:

Implement exponential backoff with jitter
Reduce the frequency of API calls
Batch operations where possible

Server and timeout errors (500/502/503/504)

Common causes:

Temporary service disruption
High load on the platform
Upstream dependency unavailable

Resolution steps:

Retry with exponential backoff (1s, 2s, 4s)
If the error persists after 3–5 retries, contact support
Log the full error response (including code) for support escalation

Service-specific error lists

Each Lerian service publishes a complete list of its error codes. Use these references to look up specific error codes:

Service	Error list
Midaz	Midaz error list
Access Manager	Access Manager error list
CRM	CRM error list
Fees Engine	Fees Engine error list
Bank Transfer (TED)	TED error list
Reporter	Reporter error list
Tracer	Tracer error list

Best practices

1. Use error codes for programmatic handling

Error codes are stable identifiers designed for automation. Map specific codes to resolution paths in your integration:

if error.code == "TRC-0100":
    # Rule not found — verify rule ID
elif error.code.startswith("TRC-01"):
    # Rule-related error — check rule configuration
elif error.code.startswith("TRC-0"):
    # Tracer validation error — check request format

2. Log errors with context

Include the full error response, the request that triggered it, and the timestamp. This makes support escalation faster and debugging more effective.

3. Handle field-level errors

When the response includes a fields object, surface those specific messages to your users rather than showing a generic error.

4. Implement circuit breakers for integrations

If you receive repeated 500, 502, or 503 errors, use a circuit breaker pattern to temporarily stop calling the failing service and prevent cascading failures.

5. Stay updated

Review the error list pages periodically. New error codes may be added as services evolve.

Overview

Integration essentials

Stability & quality

Error handling

Error response model

Field-level error details

Error code structure

Service prefixes

Number ranges

Error classification

Validation errors

Business logic errors

System errors

HTTP status codes

Retry guidance

Exponential backoff strategy

Troubleshooting by category

Missing or invalid fields (400)

Authentication and authorization (401/403)

Resource not found (404)

Conflict errors (409)

Rate limiting (429)

Server and timeout errors (500/502/503/504)

Service-specific error lists

Best practices

1. Use error codes for programmatic handling

2. Log errors with context

3. Handle field-level errors

4. Implement circuit breakers for integrations

5. Stay updated

​Error response model

​Field-level error details

​Error code structure

​Service prefixes

​Number ranges

​Error classification

​Validation errors

​Business logic errors

​System errors

​HTTP status codes

​Retry guidance

​Exponential backoff strategy

​Troubleshooting by category

​Missing or invalid fields (400)

​Authentication and authorization (401/403)

​Resource not found (404)

​Conflict errors (409)

​Rate limiting (429)

​Server and timeout errors (500/502/503/504)

​Service-specific error lists

​Best practices

​1. Use error codes for programmatic handling

​2. Log errors with context

​3. Handle field-level errors

​4. Implement circuit breakers for integrations

​5. Stay updated

Error response model

Field-level error details

Error code structure

Service prefixes

Number ranges

Error classification

Validation errors

Business logic errors

System errors

HTTP status codes

Retry guidance

Exponential backoff strategy

Troubleshooting by category

Missing or invalid fields (400)

Authentication and authorization (401/403)

Resource not found (404)

Conflict errors (409)

Rate limiting (429)

Server and timeout errors (500/502/503/504)

Service-specific error lists

Best practices

1. Use error codes for programmatic handling

2. Log errors with context

3. Handle field-level errors

4. Implement circuit breakers for integrations

5. Stay updated