Error handling

This guide explains the shape of a Lerian error response and how to respond to each kind.

What you will receive

An application/problem+json response is an RFC 9457 problem details object. Any other media type is not, and the shape it carries differs between APIs. Your API reference carries an Error handling page that names the shape that API answers.

{
  "type": "https://errors.lerian.studio/v1/RPT-0012",
  "title": "Bad Request",
  "status": 400,
  "detail": "The specified templateID is not a valid UUID. Please check the value passed.",
  "code": "RPT-0012"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The Idempotency-Key header is required for this operation and must be within the accepted length."
}

Field definitions In the problem details object:

type – A URI reference that identifies the error type.
title – A short summary of the problem type.
status – The HTTP status code.
detail – Guidance specific to this occurrence.
code – A stable identifier for the error. Use this field for programmatic handling.
errors – Optional list of per-field detail, each entry with a location and a message.
instance – Optional URI reference for this specific occurrence.

Plain envelopes differ between APIs. They differ in the field names, in whether the error sits at the top level, and in which field carries the machine-readable token. Read your API reference’s Error handling page before you write a parser.

Where an API publishes a stable code, branch on it rather than on the title or the message. Titles and messages change to improve clarity. Not every API publishes a code, and its Error handling page says whether it does.

Error codes

Code shape varies by API. You will meet a prefixed <PREFIX>-<NNNN>, a bare number, a lowercase token, and a code that a rail’s counterparty assigned. Midaz core uses bare numbers such as 0002 and 0009. Your API reference carries an Error handling page that names the shape that API uses and lists the codes it emits.

HTTP status codes

These are the status codes you will meet most often. An API can answer others, and its own Error handling page lists them.

Code	Meaning	Category
`400`	Bad Request	Validation error, so 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
`412`	Precondition Failed	A precondition on the request did not hold
`413`	Payload Too Large	The request body or the uploaded file is over the limit
`429`	Too Many Requests	Rate limit exceeded, so wait and retry
`500`	Internal Server Error	Unexpected server failure, so retry later
`502`	Bad Gateway	Upstream service returned an invalid response
`501`	Not Implemented	The deployment does not run the capability the operation needs
`503`	Service Unavailable	Service temporarily unavailable, so retry later
`504`	Gateway Timeout	Request timed out, so retry later

Retry guidance

You should not retry every error. 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	Sometimes	Retry reads with exponential backoff. Reconcile commands before retrying.
`502` / `503` / `504`	Sometimes	Retry reads with exponential backoff. Reconcile commands before retrying.

A failed command can have an unknown outcome. For commands, follow that API’s Error handling page for the idempotency key to use. Some APIs require the original key, while others reject or discard it after an uncertain provider outcome.

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

Do not repeat a 400, a 403 or a 422 unchanged. Each one names a problem in the request, so fix the request first. A 401 is worth one retry after you refresh the token, and no more.

Troubleshooting by category

Missing or invalid fields (400)

A 400 response can carry field-level detail that names the fields at fault. 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 field-level detail in the error response
Compare your request against the API reference for that endpoint

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 your environment has Access Manager enabled
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 resource ID in the URL path
List resources to confirm the ID exists
Check that you use 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 is already complete (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 reads with exponential backoff (1s, 2s, 4s). Reconcile commands before retrying them, because the original outcome can be unknown.
If the error persists after 3–5 retries, contact support
Log a redacted error response for support escalation

Service-specific error lists

Every API reference carries an Error handling page. Use it to look up a code you received. Products

API	Error list
Midaz	Midaz error list
Tracer	Tracer error list
Matcher	Matcher error list
Flowker	Flowker error list
Lender	Lender error list
Reporter	Reporter error list

Brazil Rails

API	Error list
SPB (TED)	SPB error list
SPI (Pix)	SPI error list
SLC	SLC error list
SILOC	SILOC error list
STA	STA error list
SISBAJUD	SISBAJUD error list
Consignado CLT (Dataprev)	Consignado error list

The SPI error list documents the native SPI rail contract. It is not the Pix Lerian v1.0.0 integration lane: use the Pix Lerian error list for the application plugin and mock-provider integration/testing surface. The native SPI connector is not available for use in this release. Interfaces

API	Error list
Pix Lerian	Pix Lerian error list
Pix JD	Pix JD error list
Pix BTG	Pix BTG error list
TED JD	TED JD error list
Payments BTG	Payments error list

Platform

API	Error list
Access Manager	Access Manager error list
Streaming Hub	Streaming Hub error list
Systemplane	Systemplane error list
Narya	Narya host API error list

Best practices

1. Use error codes for programmatic handling

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

if error.code == "0341":
    # Expression type: the rule expression must return a boolean
elif error.code == "0009":
    # Validation error: read `detail` for the field and the constraint
elif error.code == "Unauthenticated":
    # Authentication failed: refresh the token

2. Log errors with context

Log the operation, timestamp, status, stable error code, and a redacted response. Do not log credentials, bearer tokens, personal data, or sensitive request fields. This keeps support context useful without copying secrets or PII into logs.

3. Handle field-level errors

When the response carries field-level detail, surface those messages to your users rather than a generic error. The member that carries it differs by API. Each error list page names the member its API sends.

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 can appear as services evolve.

Overview

Integration essentials

Stability & quality

Field dictionary

Event streaming

Error handling

What you will receive

Error codes

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

​What you will receive

​Error codes

​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

What you will receive

Error codes

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