Manejo de errores

​

Modelo de respuesta de error

{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}

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

​

Detalles de error a nivel de campo

{
   "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"
   }
}

​

Estructura de códigos de error

<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

​

Rangos de números

​

Clasificación de errores

​

Errores de validación

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

​

Errores de lógica de negocio

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

​

Errores de sistema

• 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

​

Códigos de estado HTTP

​

Guía de reintentos

​

Estrategia de backoff exponencial

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

​

Resolución de problemas por categoría

​

Campos faltantes o inválidos (400)

• 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

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)

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

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)

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

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)

• 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)

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)

• Demasiadas solicitudes en un período corto

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)

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

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

​

Mejores prácticas

​

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

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

​

3. Maneja errores a nivel de campo

​

4. Implementa circuit breakers para integraciones

​

5. Mantente actualizado