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

> Aprende cómo interpretar, clasificar y resolver los errores devueltos por las APIs de Lerian, con patrones útiles para diagnosticar problemas rápidamente.

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.