Lista de errores de Tracer

La API de Tracer devuelve los errores como un objeto de detalles de problema RFC 9457, servido con el tipo de contenido application/problem+json:

{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": <http_status>,
   "detail": "<error_message>",
   "code": "<error_code>"
}

Definiciones de campos

type: un URI que identifica el tipo de error, formado por https://errors.lerian.studio/v1/ seguido del código de error.
title: un resumen breve del problema.
status: el código de estado HTTP de la respuesta.
detail: orientación detallada para resolver el error. Las tablas siguientes muestran este contenido en la columna message.
code: un identificador único y estable para el error. Suele ser una cadena numérica de cuatro dígitos tomada del registro de errores compartido de la plataforma (por ejemplo, 0347). Los fallos de autenticación son la excepción y usan la cadena literal Unauthenticated (consulta la nota siguiente).
entityType: la entidad con la que se relaciona el error (por ejemplo, Rule). Solo está presente cuando corresponde.
message: el motivo en lenguaje natural, expuesto tal cual como campo de primer nivel. Solo está presente en las respuestas 413 Payload Too Large y 504 Gateway Timeout. El resto de los errores lo omiten.

En los errores del lado del servidor (HTTP 5xx), title y detail llevan valores genéricos para que las causas internas nunca se filtren. Usa code y type para identificar el error. En los 504 por timeout, el campo message de primer nivel sigue llevando el motivo específico.

Validación en el nivel de campo Los fallos de validación de campo en el nivel de estructura devuelven el código 0009 con el título Validation Error y un detail que nombra el campo y la restricción específicos, por ejemplo transactionType must be one of [CARD WIRE PIX CRYPTO]. Ejemplos:

{
   "type": "https://errors.lerian.studio/v1/0009",
   "title": "Validation Error",
   "status": 400,
   "detail": "name is a required field",
   "code": "0009"
}

{
   "type": "https://errors.lerian.studio/v1/0341",
   "title": "Expression Type",
   "status": 400,
   "detail": "Expression must return boolean.",
   "code": "0341",
   "entityType": "Rule"
}

Dos familias de respuestas conservan una forma plana heredada {"code", "title", "message"} en lugar del objeto de detalles de problema. Las emite un middleware que se ejecuta antes de la capa de API. Fallos de autenticación: una clave de API ausente o inválida devuelve HTTP 401 con "code": "Unauthenticated", "title": "Unauthorized", y "message": "API Key missing or invalid". Haz coincidir la cadena literal Unauthenticated. Un token Bearer que se analiza correctamente pero carece del claim sub requerido devuelve HTTP 401 con "code": "0474". Capacidad de tenant: el código 0466 devuelve HTTP 503 en la misma forma plana.

Errores generales

Cualquier endpoint de la API de Tracer puede devolver estos errores.

`code`	`title`	`message`
0009	Faltan campos en la solicitud	A tu solicitud le faltan uno o más campos obligatorios: %v. Consulta la documentación para confirmar que se incluyan todos los campos necesarios en tu solicitud.
0046	Error interno del servidor	El servidor encontró un error inesperado. Vuelve a intentarlo más tarde o comunícate con soporte.
0065	Parámetro de ruta no válido	Uno o más parámetros de ruta tienen un formato incorrecto. Verifica los siguientes parámetros %v y confirma que cumplan con el formato requerido antes de volver a intentarlo.
0082	Parámetro de consulta no válido	Uno o más parámetros de consulta tienen un formato incorrecto. Verifica los siguientes parámetros ‘%v’ y confirma que cumplan con el formato requerido antes de volver a intentarlo.
0094	Solicitud incorrecta	El cuerpo de la solicitud está mal formado o contiene JSON no válido. Verifica la sintaxis e inténtalo de nuevo.
0143	Payload demasiado grande	payload demasiado grande: supera el límite de 100KB
0183	Nada que actualizar	No se proporcionó ningún campo actualizable. Incluye al menos un campo para actualizar.
0330	Contexto cancelado	Contexto cancelado o servicio no disponible.
0484	Ruta no encontrada	La ruta solicitada no existe. Verifica el método HTTP y la ruta e inténtalo de nuevo.
0485	Método no permitido	El método HTTP no está permitido para la ruta solicitada. Verifica el método e inténtalo de nuevo.
0497	Campos header de la solicitud demasiado grandes	Los campos header de la solicitud son demasiado grandes. Reduce el tamaño de los headers de la solicitud e inténtalo de nuevo.

El código 0009 también aparece con el título Validation Error cuando la validación en el nivel de campo rechaza una solicitud. Consulta la nota anterior. Los endpoints de validación y de reserva devuelven el código 0143 con HTTP 413 cuando el cuerpo de la solicitud supera el límite de 100KB. El motivo también aparece en el campo message de primer nivel. La API de Tracer devuelve el código 0497 con HTTP 431 cuando los headers de la solicitud son demasiado grandes. Devuelve el código 0484 con HTTP 404 para una ruta que el servicio no atiende. Devuelve el código 0485 con HTTP 405 para un método que la ruta no acepta.

Errores de fecha y hora

`code`	`title`	`message`
0077	Error de formato de fecha no válido	’initialDate’, ‘finalDate’, o ambos, tienen un formato incorrecto. Usa el formato ‘yyyy-mm-dd’ e inténtalo de nuevo.
0083	Error de rango de fechas no válido	Los campos ‘initialDate’ y ‘finalDate’ son obligatorios y deben tener el formato ‘yyyy-mm-dd’. Proporciona fechas válidas e inténtalo de nuevo.

Errores de paginación

`code`	`title`	`message`
0080	Límite de paginación superado	El límite de paginación supera el máximo permitido de %v elementos por página. Verifica el límite e inténtalo de nuevo.
0081	Orden de clasificación no válido	El campo ‘sort_order’ debe ser ‘asc’ o ‘desc’. Proporciona un orden de clasificación válido e inténtalo de nuevo.
0331	Límite de paginación no válido	El límite de paginación debe ser positivo.
0332	Columna de clasificación no válida	La columna de clasificación no está en la lista permitida.
0333	Cursor no válido	Cursor de paginación no válido o corrupto.
0334	Cursor con parámetros de clasificación	El cursor y los parámetros de clasificación son mutuamente excluyentes.

Errores de metadatos

Estos errores provienen del mapa metadata de una solicitud de validación (POST /v1/validations) y de una solicitud de reserva (POST /v1/reservations).

`code`	`title`	`message`
0050	Longitud de clave de metadatos superada	Una clave de metadatos supera la longitud máxima permitida de 64 caracteres. Usa una clave más corta.
0335	Entradas de metadatos superadas	Las entradas de metadatos superan el máximo de 50.
0336	Caracteres no válidos en la clave de metadatos	La clave de metadatos contiene caracteres no válidos.

La API devuelve HTTP 400 cuando una clave de metadatos supera los 64 caracteres, o cuando una solicitud tiene más de 50 entradas de metadatos.

Errores de expresión CEL

Escribes las reglas como expresiones CEL (Common Expression Language). Estos errores aparecen al crear, actualizar o evaluar la expresión de una regla.

`code`	`title`	`message`
0340	Sintaxis de expresión	Sintaxis CEL no válida.
0341	Tipo de expresión	La expresión debe devolver un valor booleano.
0342	Costo de expresión superado	Se superó el límite de costo (el costo calculado está por encima del umbral).
0343	Evaluación de expresión	Error de evaluación en tiempo de ejecución.
0344	Programa de expresión	Error al crear el programa (fase de compilación).
0345	Estimación de costo de expresión	No se pudo estimar el costo de la expresión.
0346	El monto supera la precisión	El monto supera la precisión segura para la evaluación float64 de CEL (máximo: ±2^53).
0351	Expresión no modificable	La expresión no se puede modificar en reglas que no están en estado DRAFT.

Errores de regla

`code`	`title`	`message`
0347	Regla no encontrada	No se encontró la regla por ID.
0348	El nombre de la regla ya existe	El nombre de la regla debe ser único.
0349	Estado de regla no válido	Transición de estado de regla no válida.
0350	Error de evaluación de regla	Falló la evaluación de la regla.
0352	Entrada de regla nula	La entrada de la regla no puede ser nula.
0353	Nombre de regla obligatorio	El nombre de la regla es obligatorio.
0354	Nombre de regla demasiado largo	El nombre de la regla supera la longitud máxima (255).
0355	Expresión de regla obligatoria	La expresión de la regla es obligatoria.
0356	Expresión de regla demasiado larga	La expresión de la regla supera la longitud máxima (5000).
0357	Acción de regla no válida	La acción debe ser una de [ALLOW, DENY, REVIEW].
0358	Scope de regla no válido	El scope debe tener al menos un campo definido.
0359	Descripción de regla demasiado larga	La descripción de la regla supera la longitud máxima (1000).
0360	Demasiados scopes de regla	Los scopes de la regla superan el máximo (100).
0437	Caché de reglas no lista	La caché de reglas no está lista.
0441	El nombre de la regla ya existe en este contexto	El nombre de la regla ya existe en este contexto.

Errores de límite

`code`	`title`	`message`
0362	Límite no encontrado	No se encontró el límite por ID.
0363	Cambio de estado de límite no válido	Transición de estado de límite no válida.
0364	Tipo de límite no válido	Tipo de límite no válido.
0365	Monto máximo de límite no válido	MaxAmount debe ser positivo.
0366	Activo de límite no válido	El activo debe ser un código ISO 4217 válido.
0367	Scope de límite no válido	Falló la validación del scope.
0368	Nombre de límite obligatorio	El nombre del límite es obligatorio.
0369	Nombre de límite demasiado largo	El nombre del límite supera la longitud máxima.

Errores de evento de auditoría

`code`	`title`	`message`
0381	Evento de auditoría no encontrado	No se encontró el evento de auditoría.
0382	Filtros de evento de auditoría no válidos	Parámetros de filtro de evento de auditoría no válidos.

Errores de solicitud de validación

Los endpoints de validación de transacciones (POST /v1/validations y las consultas de validación) devuelven estos errores.

`code`	`title`	`message`
0413	ID de solicitud obligatorio	RequestId es obligatorio.
0414	Tipo de transacción no válido	transactionType no válido.
0415	Monto no positivo	El monto debe ser positivo.
0416	Activo obligatorio	El activo es obligatorio.
0417	Activo no válido	El activo debe ser un código ISO 4217 válido.
0418	Marca de tiempo obligatoria	La marca de tiempo es obligatoria.
0419	Marca de tiempo futura	La marca de tiempo no puede estar en el futuro.
0420	Cuenta obligatoria	La cuenta es obligatoria.
0421	Marca de tiempo demasiado antigua	La marca de tiempo está demasiado en el pasado.
0422	Gateway Timeout	timeout de validación
0423	ID de segmento obligatorio	SegmentId es obligatorio cuando se proporciona segment.
0424	ID de portafolio obligatorio	PortfolioId es obligatorio cuando se proporciona portfolio.
0425	Subtipo demasiado largo	SubType supera la longitud máxima de 50 caracteres.
0426	Tipo de cuenta no válido	Account.type debe ser checking, savings o credit.
0427	Estado de cuenta no válido	Account.status debe ser active, suspended o closed.
0428	Categoría de comercio no válida	Merchant.category debe ser un código MCC de 4 dígitos.
0429	País de comercio no válido	Merchant.country debe ser ISO 3166-1 alpha-2.
0430	ID de comercio obligatorio	Merchant.id es obligatorio cuando se proporciona merchant.
0431	Filtros de validación de transacción no válidos	Parámetros de filtro de validación de transacción no válidos.
0432	Validación de transacción no encontrada	No se encontró el registro de validación de transacción.
0433	Gateway Timeout	se superó el timeout de la consulta

La API devuelve los códigos 0422 y 0433 con HTTP 504 Gateway Timeout: 0422 cuando la evaluación de una validación supera su plazo, 0433 cuando lo supera una consulta de lista de validaciones. Como en todas las respuestas 5xx, detail lleva un valor genérico. El campo message de primer nivel lleva el motivo específico.

Errores de reserva

Los endpoints de reserva de uso (/reservations) devuelven estos errores. Forman la superficie de dos fases de reservar, confirmar y liberar. Las solicitudes de reserva también pueden devolver los errores generales y de solicitud de validación indicados antes.

`code`	`title`	`message`
0476	ID de transacción de reserva obligatorio	Reserva: transactionId es obligatorio.
0480	Estado de reserva no válido	Reserva: status debe ser uno de RESERVED, CONFIRMED, RELEASED, EXPIRED.
0482	Reserva no encontrada	Reserva: no se encontró la reserva.

| 0487 | Tenant obligatorio en la reserva | Reserva: el id del tenant es obligatorio en la superficie de reserva multi-tenant. |

Errores de multi-tenant y autenticación

La instancia devuelve HTTP 503 con un header Retry-After cuando alcanza su tope de workers de tenant por pod. Los clientes deben aplicar backoff y reintentar. Un token Bearer que se analiza correctamente pero carece del claim sub requerido devuelve HTTP 401.

`code`	`title`	`message`
0466	Capacidad de tenant alcanzada	Se alcanzó la capacidad del tenant; vuelve a intentarlo en breve
0474	No autorizado	Al token Bearer le falta el claim ‘sub’ requerido; no se puede atribuir la identidad.

Errores de arranque de multi-tenant

Estos códigos aparecen solo al iniciar el servicio, cuando MULTI_TENANT_ENABLED=true y falta una configuración obligatoria o es incompatible. Aparecen en los logs de inicio e impiden que el servicio arranque. Nunca llegan a los consumidores de la API /v1/*.

`code`	`title`	`message`
0451	Config multi-tenant obligatoria	Configuración multi-tenant: cfg es obligatorio.
0452	Logger multi-tenant obligatorio	Configuración multi-tenant: logger es obligatorio.
0453	URL multi-tenant obligatoria	MULTI_TENANT_URL debe estar definida cuando MULTI_TENANT_ENABLED=true.
0454	URL multi-tenant no válida	MULTI_TENANT_URL debe ser una URL absoluta válida con esquema y host.
0455	API key de servicio multi-tenant obligatoria	MULTI_TENANT_SERVICE_API_KEY debe estar definida cuando MULTI_TENANT_ENABLED=true.
0456	Host de Redis multi-tenant obligatorio	MULTI_TENANT_REDIS_HOST debe estar definida cuando MULTI_TENANT_ENABLED=true.
0457	Autenticación de plugin multi-tenant obligatoria	MULTI_TENANT_ENABLED=true requiere PLUGIN_AUTH_ENABLED=true.
0458	Conflicto de validación exclusiva por API key multi-tenant	MULTI_TENANT_ENABLED=true es incompatible con API_KEY_ENABLED_ONLY_VALIDATION=true.

Errores del readiness probe

El endpoint operativo /readyz y el ciclo de vida del worker-supervisor exponen estos códigos. Aparecen en el campo error de la respuesta JSON de /readyz (que lleva solo el código), no en las respuestas de la API /v1/*. El title y el message siguientes describen cada código como referencia para el operador. El ciclo de /readyz verifica cinco dependencias. Siempre verifica postgres y rule_cache. Verifica redis y tenant_manager solo en modo multi-tenant, y las omite en caso contrario. streaming es informativo. Aparece en las verificaciones y en las métricas, pero nunca fuerza un 503.

`code`	`title`	`message`
0436	Falló el calentamiento de la caché de reglas	Falló el calentamiento de la caché de reglas.
0459	Conexión de Postgres no establecida en readyz	Postgres readyz: conexión no establecida.
0460	Falló la conexión de Postgres en readyz	Postgres readyz: falló la conexión.
0461	Falló el ping de Postgres en readyz	Postgres readyz: falló el ping.
0462	Dependencias no saludables en readyz	Agregado de /readyz: una o más dependencias no están saludables.
0463	Caché no lista en readyz	Rule_cache readyz: la caché no está lista.
0464	Caché desactualizada en readyz	Rule_cache readyz: datos de la caché desactualizados.
0465	El supervisor se está cerrando	Worker supervisor: cerrándose, rechaza crear nuevos workers de tenant.
0493	Conexión de Redis no establecida en readyz	Redis readyz: conexión no establecida.
0494	Falló el ping de Redis en readyz	Redis readyz: falló el ping.
0495	Tenant manager no disponible en readyz	Tenant_manager readyz: servicio no disponible.
0496	Streaming no saludable en readyz	Streaming readyz: productor no saludable.

Primeros pasos

API de Validaciones

API de Reglas

API de Límites

API de Reservas

API de Eventos de Auditoría

Manejo de errores

Eventos

Lista de errores de Tracer

Errores generales

Errores de fecha y hora

Errores de paginación

Errores de metadatos

Errores de expresión CEL

Errores de regla

Errores de límite

Errores de evento de auditoría

Errores de solicitud de validación

Errores de reserva

Errores de multi-tenant y autenticación

Errores de arranque de multi-tenant

Errores del readiness probe

​Errores generales

​Errores de fecha y hora

​Errores de paginación

​Errores de metadatos

​Errores de expresión CEL

​Errores de regla

​Errores de límite

​Errores de evento de auditoría

​Errores de solicitud de validación

​Errores de reserva

​Errores de multi-tenant y autenticación

​Errores de arranque de multi-tenant

​Errores del readiness probe

Errores generales

Errores de fecha y hora

Errores de paginación

Errores de metadatos

Errores de expresión CEL

Errores de regla

Errores de límite

Errores de evento de auditoría

Errores de solicitud de validación

Errores de reserva

Errores de multi-tenant y autenticación

Errores de arranque de multi-tenant

Errores del readiness probe