> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Learn how to interpret and resolve error responses returned by Lerian APIs, including the error envelopes, HTTP status codes, and field-level detail.

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](https://www.rfc-editor.org/rfc/rfc9457) problem details object. Your API reference carries an **Error handling** page that names the shape that API answers.

<CodeGroup>
  ```json application/problem+json theme={null}
  {
    "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"
  }
  ```

  ```json application/json theme={null}
  {
    "code": "PIX-0030",
    "title": "Idempotency Key Required",
    "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
  }
  ```
</CodeGroup>

**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.
* **`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.

<Tip>
  Where an API publishes a stable code, branch on it. Not every API publishes a code, and its
  **Error handling** page says whether it does.
</Tip>

## 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 |
| - | - |
| `400` | Bad Request |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found |
| `409` | Conflict |
| `422` | Unprocessable Entity |
| `412` | Precondition Failed |
| `413` | Payload Too Large |
| `429` | Too Many Requests |
| `500` | Internal Server Error |
| `502` | Bad Gateway |
| `501` | Not Implemented |
| `503` | Service Unavailable |
| `504` | Gateway Timeout |

## Retry guidance

***

You should not retry every error. The following table helps you decide:

| Error type | Retryable | Recommended action |
| - | - | - |
| `400` | No | Fix the request payload |
| `401` | After a token refresh | Check credentials |
| `403` | No | Check permissions |
| `404` not found | No | Verify the resource ID |
| `409` conflicts | Sometimes | Check current state, then retry if the conflict is resolved |
| `422` | No | Fix the cause the error names |
| `429` rate limit | Sometimes | Wait, then retry reads. Reconcile commands before retrying. |
| `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. |

<Warning>
  A failed command can have an unknown outcome. For commands, follow that API's reference for the idempotency key to use. Some APIs require the original key, while others reject or discard it after an uncertain provider outcome.
</Warning>

### Exponential backoff strategy

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

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

<Warning>
  Do not repeat a `400`, a `403` or a `422` unchanged. A `401` is worth one retry after you refresh the token, and no more.
</Warning>

## 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:**

1. Read the field-level detail in the error response
2. Compare your request against the API reference for that endpoint

### Authentication and authorization (401/403)

**Common causes:**

* Missing credential
* Expired or revoked token
* Token does not grant access to the requested endpoint

**Resolution steps:**

1. Verify that the request carries the credential your API expects
2. Request a new token if the current one has expired
3. Check that the caller has 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:**

1. Verify the resource ID in the URL path
2. List resources to confirm the ID exists

### 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:**

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

### Rate limiting (429)

**Common causes:**

* Too many requests in a short period

**Resolution steps:**

1. Implement exponential backoff with jitter
2. Reduce the frequency of API calls
3. 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:**

1. Retry reads with exponential backoff (1s, 2s, 4s). Reconcile commands before retrying them, because the original outcome can be unknown.
2. If the error persists after 3–5 retries, contact support
3. 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](/en/reference/products/midaz/error-list) |
| Tracer | [Tracer error list](/en/reference/products/tracer/tracer-error-list) |
| Matcher | [Matcher error list](/en/reference/products/matcher/matcher-error-list) |
| Flowker | [Flowker error list](/en/reference/products/flowker/flowker-error-list) |
| Lender | [Lender error list](/en/reference/products/lender/lender-error-list) |
| Reporter | [Reporter error list](/en/reference/products/reporter/reporter-error-list) |

**Brazil Rails**

| API | Error list |
| - | - |
| SPB (TED) | [SPB error list](/en/reference/rails/spb/spb-error-list) |
| SPI (Pix) | [SPI error list](/en/reference/rails/spi/spi-error-list) |
| SLC | [SLC error list](/en/reference/rails/slc/slc-error-list) |
| SILOC | [SILOC error list](/en/reference/rails/siloc/siloc-error-list) |
| STA | [STA error list](/en/reference/rails/sta/sta-error-list) |
| SISBAJUD | [SISBAJUD error list](/en/reference/rails/sisbajud/sisbajud-error-list) |
| Consignado CLT (Dataprev) | [Consignado error list](/en/reference/rails/consignado/consignado-error-list) |

**Interfaces**

| API | Error list |
| - | - |
| Pix Lerian | [Pix Lerian error list](/en/reference/interfaces/pix-lerian/pix-lerian-error-list) |
| Pix JD | [Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list) |
| Pix BTG | [Pix BTG error list](/en/reference/interfaces/pix-btg/indirect-pix-error-list) |
| TED JD | [TED JD error list](/en/reference/interfaces/ted-jd/ted-error-list) |
| Payments BTG | [Payments error list](/en/reference/interfaces/payments-btg/payments-error-list) |

**Platform**

| API | Error list |
| - | - |
| Access Manager | [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list) |
| Streaming Hub | [Streaming Hub error list](/en/reference/platform/streaming-hub/streaming-hub-error-list) |
| Systemplane | [Systemplane error list](/en/reference/platform/systemplane/systemplane-error-list) |
| Narya | [Narya host API error list](/en/reference/platform/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. Take the codes from your API's error list page.

### 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.