Skip to main content
Esta guía explica la forma de una respuesta de error de Lerian y cómo responder a cada tipo.

​
Qué recibirás

Una respuesta application/problem+json es un objeto de detalles de problema de RFC 9457. Cualquier otro tipo de medio no lo es, y la forma que transporta varía entre APIs. La referencia de tu API incluye una página de Manejo de errores que indica la forma con la que esa API responde.
Definiciones de los campos En el objeto de detalles de problema:
  • type – Una referencia URI que identifica el tipo de error.
  • title – Un resumen breve del tipo de problema.
  • status – El código de estado HTTP.
  • detail – Orientación específica para esta ocurrencia.
  • code – Un identificador estable para el error. Usa este campo para el manejo programático.
  • errors – Lista opcional de detalle por campo, cada entrada con un location y un message.
  • instance – Referencia URI opcional para esta ocurrencia específica.
Los envelopes simples difieren entre APIs. Difieren en los nombres de campo, en si el error está en el nivel superior y en qué campo lleva el token legible por máquina. Lee la página de Manejo de errores de la referencia de tu API antes de escribir un analizador.
Cuando una API publica un código estable, ramifica tu lógica sobre ese código en lugar del título o el mensaje. Los títulos y los mensajes cambian para mejorar la claridad. No todas las APIs publican un código, y su página de Manejo de errores indica si lo hace.

​
Códigos de error

La forma del código varía según la API. Encontrarás un <PREFIX>-<NNNN> con prefijo, un número simple, un token en minúsculas y un código que asignó la contraparte de un riel. El núcleo de Midaz usa números simples como 0002 y 0009. La referencia de tu API incluye una página de Manejo de errores que indica la forma que usa esa API y lista los códigos que emite.

​
Códigos de estado HTTP

Estos son los códigos de estado que encontrarás con más frecuencia. Una API puede responder con otros, y su propia página de Manejo de errores los lista.

​
Orientación sobre reintentos

No se recomienda reintentar cada error. La siguiente tabla te ayuda a decidir:
Un comando fallido puede tener un resultado desconocido. Para los comandos, sigue la página de Manejo de errores de esa API para saber qué clave de idempotencia usar. Algunas APIs exigen la clave original, mientras que otras la rechazan o la descartan después de un resultado incierto del proveedor.

​
Estrategia de backoff exponencial

Para los errores reintentables, usa backoff exponencial para no saturar el servicio:
  1. Primer reintento: espera 1 segundo
  2. Segundo reintento: espera 2 segundos
  3. Tercer reintento: espera 4 segundos
  4. Reintentos máximos: detente después de 3 a 5 intentos
  5. Jitter: agrega un pequeño retraso aleatorio (0 a 500 ms) a cada espera para evitar el thundering herd
No repitas un 400, un 403 o un 422 sin cambios. Cada uno señala un problema en la solicitud, así que corrige la solicitud primero. Un 401 vale un solo reintento después de renovar el token, y no más.

​
Solución de problemas por categoría

​
Campos faltantes o inválidos (400)

Una respuesta 400 puede llevar detalle por campo que señala los campos responsables. Causas comunes:
  • Falta un campo obligatorio en el cuerpo de la solicitud
  • El valor del campo no coincide con el tipo esperado (por ejemplo, texto en lugar de UUID)
  • El valor del campo supera la longitud máxima
  • Campos adicionales inesperados en el cuerpo de la solicitud
Pasos de resolución:
  1. Lee el detalle por campo en la respuesta de error
  2. Compara tu solicitud con la referencia de la API para ese endpoint

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

Causas comunes:
  • Falta el header Authorization
  • Token expirado o revocado
  • El token no otorga acceso al endpoint solicitado
Pasos de resolución:
  1. Confirma que tu entorno tenga Access Manager habilitado
  2. Verifica que el token esté presente en el header Authorization
  3. Solicita un token nuevo si el actual expiró
  4. Verifica que el ámbito del token incluya los permisos requeridos

​
Recurso no encontrado (404)

Causas comunes:
  • ID de recurso incorrecto en la ruta de la URL
  • El recurso se eliminó de forma lógica (soft delete)
  • El recurso pertenece a otra organización o ledger
Pasos de resolución:
  1. Verifica el ID del recurso en la ruta de la URL
  2. Lista los recursos para confirmar que el ID existe
  3. Verifica que uses los parámetros de ruta organizationId y ledgerId correctos

​
Errores de conflicto (409)

Causas comunes:
  • Crear un recurso con un nombre que ya existe (por ejemplo, nombre de ledger duplicado, nombre de regla duplicado)
  • Intentar una operación que ya se completó (por ejemplo, transacción duplicada)
Pasos de resolución:
  1. Lee el mensaje de error para identificar qué campo causó el conflicto
  2. Usa un valor distinto (por ejemplo, renombra) u obtén el recurso existente en su lugar
  3. Para operaciones idempotentes, verifica que el recurso existente coincida con tu intención

​
Rate limit (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 las llamadas a la API
  3. Agrupa operaciones en lotes cuando sea posible

​
Errores de servidor y de tiempo de espera (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 las lecturas con backoff exponencial (1 s, 2 s, 4 s). Concilia los comandos antes de reintentarlos, porque el resultado original puede ser desconocido.
  2. Si el error persiste después de 3 a 5 reintentos, contacta a soporte
  3. Registra una respuesta de error redactada para la escalación a soporte

​
Listas de errores por servicio

Cada referencia de API incluye una página de Manejo de errores. Úsala para buscar un código que recibiste. Productos Rieles Brasil La lista de errores de SPI documenta el contrato del riel nativo de SPI. No es la vía de integración de Pix Lerian v1.0.0: usa la lista de errores de Pix Lerian para el plugin de aplicación y la superficie de integración/pruebas con el proveedor simulado. El conector nativo de SPI no está disponible para uso en esta versión. Interfaces Plataforma

​
Mejores prácticas

​
1. Usa los códigos de error para el manejo programático

Los códigos de error son identificadores estables para la automatización. Asigna códigos específicos a rutas de resolución en tu integración:

​
2. Registra los errores con contexto

Registra la operación, la marca de tiempo, el estado, el código de error estable y una respuesta redactada. No registres credenciales, tokens bearer, datos personales ni campos sensibles de la solicitud. Esto mantiene el contexto útil para soporte sin copiar secretos ni PII en los registros.

​
3. Maneja los errores por campo

Cuando la respuesta lleva detalle por campo, muestra esos mensajes a tus usuarios en lugar de un error genérico. El miembro que lo lleva varía según la API. Cada página de lista de errores indica el miembro que envía su API.

​
4. Implementa circuit breakers para las integraciones

Si recibes errores 500, 502 o 503 repetidos, usa un patrón de circuit breaker para dejar de llamar temporalmente al servicio que falla y evitar fallas en cascada.

​
5. Mantente actualizado

Revisa las páginas de listas de errores periódicamente. Pueden aparecer nuevos códigos de error a medida que los servicios evolucionan.