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

# Manejo de errores

> Cómo interpretar, clasificar y resolver errores devueltos por las APIs de Lerian.

Al integrar con las APIs de Lerian, un manejo robusto de errores es esencial para una experiencia de usuario fluida y un rendimiento de aplicación resiliente. Esta guía explica cómo están estructurados los errores, cómo clasificarlos y cómo responder a diferentes categorías de error.

## Modelo de respuesta de error

***

Todas las APIs de Lerian devuelven un objeto de error estructurado para cada error. El formato es consistente en todos los servicios:

```json theme={null}
{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}
```

**Definiciones de campos:**

* `code`: Un identificador único y estable para el error. Usa este campo para el manejo programático de errores.
* `title`: Un resumen breve del problema.
* `message`: Orientación detallada y legible para resolver el error.

<Tip>
  Siempre usa el campo `code` para identificar errores programáticamente. Los títulos y mensajes pueden evolucionar para mejorar la claridad, pero los códigos de error permanecen estables.
</Tip>

### Detalles de error a nivel de campo

Cuando un error se relaciona con campos específicos en el payload de la solicitud, la respuesta incluye un objeto `fields` con detalles granulares:

<CodeGroup>
  ```json Campos requeridos faltantes theme={null}
  {
     "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"
     }
  }
  ```

  ```json Valores de campo inválidos theme={null}
  {
     "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"
     }
  }
  ```

  ```json Campos inesperados theme={null}
  {
     "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"
     }
  }
  ```
</CodeGroup>

## Estructura de códigos de error

***

Cada código de error sigue un formato estandarizado que identifica tanto el servicio como el error específico:

```
<PREFIX>-<NNNN>
```

* **PREFIX** (3 letras): Identifica el servicio o plugin que produjo el error.
* **NNNN** (4 dígitos): Un número único dentro de ese servicio.

### Prefijos de servicio

| Prefijo | Servicio                       |
| ------- | ------------------------------ |
| **AUT** | Access Manager (autenticación) |
| **IDE** | Access Manager (identidad)     |
| **CRM** | CRM                            |
| **FEE** | Fees Engine                    |
| **PIX** | PIX                            |
| **BTF** | Bank Transfer (TED)            |
| **TPL** | Reporter                       |
| **TRC** | Tracer                         |

<Note>
  Midaz core usa códigos solo numéricos (ej., `0002`, `0009`) sin prefijo. Todos los demás servicios incluyen su prefijo de 3 letras.
</Note>

### Rangos de números

Los códigos de error están organizados en rangos que indican el origen del error:

| Rango         | Categoría               | Descripción                                                          |
| ------------- | ----------------------- | -------------------------------------------------------------------- |
| `0001`–`0099` | Sistema y middleware    | Autenticación, autorización, encabezados, rate limiting              |
| `0100`–`0999` | Específico del servicio | Validación, lógica de negocio y errores de dominio dentro del plugin |
| `1000`–`1999` | Integración externa     | Errores originados en proveedores externos o servicios upstream      |

Esta estructura te permite identificar rápidamente si un error proviene de tu solicitud (números bajos), de la lógica de negocio del servicio (rango medio) o de una dependencia externa (1000+).

## Clasificación de errores

***

Comprender el tipo de error te ayuda a decidir cómo responder. Los errores de Lerian se clasifican en tres categorías:

### Errores de validación

Errores causados por datos incorrectos o faltantes en la solicitud.

**Características:**

* Estado HTTP `400` (Bad Request)
* Incluyen un objeto `fields` cuando campos específicos son los causantes
* Siempre prevenibles validando los datos antes de enviar

**Ejemplos:** Campos requeridos faltantes, UUIDs inválidos, valores de enumeración no soportados, campos que exceden la longitud máxima.

**Qué hacer:** Revisa el objeto `fields` para detalles específicos. Corrige los datos y reintenta.

### Errores de lógica de negocio

Errores causados por operaciones que violan reglas de dominio o restricciones de estado de recursos.

**Características:**

* Estado HTTP `404` (Not Found), `409` (Conflict) o `422` (Unprocessable Entity)
* Indican que la solicitud es sintácticamente válida pero no puede procesarse

**Ejemplos:** Recurso no encontrado, conflictos de nombre duplicado, transiciones de estado inválidas (ej., activar una regla ya activa), saldo insuficiente.

**Qué hacer:** Verifica que el recurso existe y está en el estado esperado. Revisa el mensaje de error para la restricción específica que fue violada.

### Errores de sistema

Errores causados por problemas de infraestructura, timeouts o fallas inesperadas.

**Características:**

* Estado HTTP `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable) o `504` (Gateway Timeout)
* No son causados por tus datos — la misma solicitud puede tener éxito más tarde

**Ejemplos:** Error interno del servidor, servicio temporalmente no disponible, gateway timeout.

**Qué hacer:** Reintenta con backoff exponencial (consulta la guía abajo). Si el error persiste, contacta a soporte.

## Códigos de estado HTTP

***

Las APIs de Lerian usan un conjunto enfocado de códigos de estado HTTP:

| Código | Significado           | Categoría                                                        |
| ------ | --------------------- | ---------------------------------------------------------------- |
| `400`  | Bad Request           | Error de validación — corrige la solicitud                       |
| `401`  | Unauthorized          | Credenciales de autenticación faltantes o inválidas              |
| `403`  | Forbidden             | Credenciales válidas pero permisos insuficientes                 |
| `404`  | Not Found             | El recurso solicitado no existe                                  |
| `409`  | Conflict              | La operación entra en conflicto con el estado actual del recurso |
| `422`  | Unprocessable Entity  | Sintaxis válida pero viola reglas de negocio                     |
| `429`  | Too Many Requests     | Límite de tasa excedido — espera y reintenta                     |
| `500`  | Internal Server Error | Falla inesperada del servidor — reintenta más tarde              |
| `502`  | Bad Gateway           | El servicio upstream devolvió una respuesta inválida             |
| `503`  | Service Unavailable   | Servicio temporalmente no disponible — reintenta más tarde       |
| `504`  | Gateway Timeout       | La solicitud expiró — reintenta más tarde                        |

## Guía de reintentos

***

No todos los errores deben reintentarse. La siguiente tabla te ayuda a decidir:

| Tipo de error                 | Reintentable | Acción recomendada                                                     |
| ----------------------------- | ------------ | ---------------------------------------------------------------------- |
| `400` errores de validación   | No           | Corrige el payload de la solicitud                                     |
| `401` / `403` errores de auth | No           | Verifica credenciales y permisos                                       |
| `404` no encontrado           | No           | Verifica el ID del recurso                                             |
| `409` conflictos              | A veces      | Verifica el estado actual, luego reintenta si el conflicto se resolvió |
| `422` lógica de negocio       | No           | Ajusta la operación para cumplir con las reglas de negocio             |
| `429` límite de tasa          | Sí           | Espera la ventana de reintento, luego reintenta                        |
| `500` errores internos        | Sí           | Reintenta con backoff exponencial                                      |
| `502` / `503` / `504`         | Sí           | Reintenta con backoff exponencial                                      |

### Estrategia de backoff exponencial

Para errores reintentables, usa backoff exponencial para evitar sobrecargar el servicio:

1. **Primer reintento**: Espera 1 segundo
2. **Segundo reintento**: Espera 2 segundos
3. **Tercer reintento**: Espera 4 segundos
4. **Máximo de reintentos**: Detente después de 3–5 intentos
5. **Jitter**: Agrega un pequeño retraso aleatorio (0–500ms) a cada espera para prevenir avalanchas

<Warning>
  Nunca reintentes automáticamente errores `400`, `401`, `403` o `422`. Estos indican problemas con tu solicitud que deben corregirse antes de reintentar.
</Warning>

## Resolución de problemas por categoría

***

### Campos faltantes o inválidos (400)

La mayoría de errores `400` incluyen un objeto `fields` que te indica exactamente qué campos necesitan atención.

**Causas comunes:**

* Campo requerido omitido del cuerpo de la solicitud
* Valor del campo no coincide con el tipo esperado (ej., string en lugar de UUID)
* Valor del campo excede la longitud máxima
* Campos extra inesperados en el cuerpo de la solicitud

**Pasos de resolución:**

1. Lee el objeto `fields` en la respuesta de error
2. Compara tu solicitud con la referencia de API para ese endpoint
3. Verifica que los nombres de campo usen `lowerCamelCase` (no `snake_case`)
4. Verifica que las fechas usen formato ISO 8601 con sufijo `Z`
5. Verifica que los UUIDs sean formato v4 válido

### Autenticación y autorización (401/403)

**Causas comunes:**

* Encabezado `Authorization` faltante
* Token expirado o revocado
* El token no otorga acceso al endpoint solicitado

**Pasos de resolución:**

1. Confirma que Access Manager está habilitado en tu entorno
2. Verifica que el token está presente en el encabezado `Authorization`
3. Solicita un nuevo token si el actual ha expirado
4. Verifica que el alcance del token incluya los permisos requeridos

### Recurso no encontrado (404)

**Causas comunes:**

* ID de recurso incorrecto en la ruta URL
* Recurso fue eliminado (soft-delete)
* Recurso pertenece a una organización o ledger diferente

**Pasos de resolución:**

1. Verifica el formato del ID (debe ser un UUID válido)
2. Lista los recursos para confirmar que el ID existe
3. Verifica que estás usando los parámetros de ruta `organizationId` y `ledgerId` correctos

### Errores de conflicto (409)

**Causas comunes:**

* Crear un recurso con un nombre que ya existe (ej., nombre de ledger duplicado, nombre de regla duplicado)
* Intentar una operación que ya se completó (ej., transacción duplicada)

**Pasos de resolución:**

1. Lee el mensaje de error para identificar qué campo causó el conflicto
2. Usa un valor diferente (ej., renombra) u obtén el recurso existente en su lugar
3. Para operaciones idempotentes, verifica que el recurso existente coincida con tu intención

### Límite de tasa (429)

**Causas comunes:**

* Demasiadas solicitudes en un período corto

**Pasos de resolución:**

1. Implementa backoff exponencial con jitter
2. Reduce la frecuencia de llamadas a la API
3. Agrupa operaciones donde sea posible

### Errores de servidor y timeout (500/502/503/504)

**Causas comunes:**

* Interrupción temporal del servicio
* Alta carga en la plataforma
* Dependencia upstream no disponible

**Pasos de resolución:**

1. Reintenta con backoff exponencial (1s, 2s, 4s)
2. Si el error persiste después de 3–5 reintentos, contacta a soporte
3. Registra la respuesta de error completa (incluyendo `code`) para escalamiento a soporte

## Listas de errores por servicio

***

Cada servicio de Lerian publica una lista completa de sus códigos de error. Usa estas referencias para buscar códigos de error específicos:

| Servicio            | Lista de errores                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| Midaz               | [Lista de errores de Midaz](/es/reference/midaz/error-list)                                      |
| Access Manager      | [Lista de errores de Access Manager](/es/reference/access-manager/access-manager-error-list)     |
| CRM                 | [Lista de errores de CRM](/es/reference/midaz/crm/crm-error-list)                                |
| Fees Engine         | [Lista de errores de Fees Engine](/es/reference/midaz/plugins/fees-engine/fee-engine-error-list) |
| Bank Transfer (TED) | [Lista de errores de TED](/es/reference/midaz/plugins/ted/ted-error-list)                        |
| Reporter            | [Lista de errores de Reporter](/es/reference/reporter/reporter-error-list)                       |
| Tracer              | [Lista de errores de Tracer](/es/reference/tracer/tracer-error-list)                             |

## Mejores prácticas

***

### 1. Usa códigos de error para manejo programático

Los códigos de error son identificadores estables diseñados para automatización. Mapea códigos específicos a rutas de resolución en tu integración:

```
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. Registra errores con contexto

Incluye la respuesta de error completa, la solicitud que la disparó y la marca de tiempo. Esto hace que la escalamiento a soporte sea más rápido y la depuración más efectiva.

### 3. Maneja errores a nivel de campo

Cuando la respuesta incluye un objeto `fields`, muestra esos mensajes específicos a tus usuarios en lugar de mostrar un error genérico.

### 4. Implementa circuit breakers para integraciones

Si recibes errores `500`, `502` o `503` repetidos, usa un patrón de circuit breaker para detener temporalmente las llamadas al servicio fallando y prevenir fallas en cascada.

### 5. Mantente actualizado

Revisa las páginas de lista de errores periódicamente. Se pueden agregar nuevos códigos de error a medida que los servicios evolucionan.