Lista de errores de Tracer

Las API de Tracer devuelven un objeto de error estructurado con un código estable, un estado HTTP y un mensaje para que puedas diagnosticar problemas y dirigirlos al equipo correcto.

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 por API key usan la cadena literal Unauthenticated (consulta la nota siguiente). Los rechazos de Access Manager y Tenant Manager usan sus propios códigos, incluidos los códigos de Errores de capacidad y autenticación.
• 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. Está presente en las respuestas 413 Payload Too Large y 504 Gateway Timeout.

En los errores del lado del servidor (HTTP 5xx), title y detail llevan valores genéricos. Los rechazos de Access Manager y Tenant Manager conservan sus propios title y detail. 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 scope at index 0: scheme must be 1 to 50 characters of A-Z, 0-9, _ or - after trimming and upper-casing.

Ejemplos:

Missing required field

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

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.

El endpoint de validación devuelve 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 POST /v1/validations/rules-only).

code	title	message
0050	Longitud de clave de metadatos superada	Una clave de metadatos supera la longitud máxima permitida de 100 bytes. Usa una clave más corta.

La API devuelve HTTP 400 cuando una clave de metadatos supera los 100 bytes.

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.
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 no puede ser negativo.
0366	Activo de límite no válido	El activo debe tener de 1 a 100 letras mayúsculas.
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 (255 caracteres).
0371	Caracteres no válidos en el nombre del límite	El nombre del límite contiene caracteres no válidos.
0372	Caracteres no válidos en la descripción del límite	La descripción del límite contiene caracteres no válidos.
0374	Descripción de límite demasiado larga	La descripción del límite supera la longitud máxima (1000 caracteres).
0379	Entrada de límite nula	La entrada del límite no puede ser nula.
0380	Campo inmutable de límite	No se puede modificar un campo inmutable (limitType, asset, resetTime).
0438	Discrepancia en la ventana de tiempo del límite	ActiveTimeStart y activeTimeEnd deben estar ambos definidos o ambos ser nulos.
0440	Formato de hora del día no válido	Formato de hora del día no válido, se esperaba HH:MM.
0442	El nombre del límite ya existe	El nombre del límite ya existe.
0447	Formato de inicio personalizado no válido	Formato de customStartDate no válido, se esperaba RFC3339.
0448	Formato de fin personalizado no válido	Formato de customEndDate no válido, se esperaba RFC3339.
0449	Fechas personalizadas obligatorias	CustomStartDate y customEndDate son obligatorios para el limitType CUSTOM.
0537	Hora de reinicio del límite no permitida	ResetTime solo se permite para el limitType DAILY, WEEKLY o MONTHLY.
0538	Hora de reinicio del límite dentro de la ventana	ResetTime no debe caer dentro de la ventana de tiempo activa (puede ser igual a activeTimeStart o activeTimeEnd).

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, POST /v1/validations/rules-only 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	scheme (o transactionType) es obligatorio y debe tener de 1 a 50 caracteres de A-Z, 0-9, _ o -, después de eliminar los espacios de los extremos y convertir a mayúsculas
0415	Monto no positivo	El monto debe ser positivo.
0416	Activo obligatorio	El activo es obligatorio.
0417	Activo no válido	El activo debe tener de 1 a 100 letras mayúsculas.
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.
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 tener como máximo 256 caracteres.
0427	Estado de cuenta no válido	Account.status debe tener como máximo 50 caracteres.
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.
0540	Conflicto de alias del esquema	scheme y transactionType deben tener el mismo valor
0084	Clave de idempotencia duplicada	La clave de idempotencia la tiene una solicitud que aún se está procesando o una solicitud distinta. Para reintentar la misma solicitud, espera y vuelve a intentar con la misma clave. Usa una clave nueva solo para una solicitud distinta.

La API devuelve el código 0084 con HTTP 409 cuando una solicitud de validación reutiliza un requestId que otro cuerpo o la otra ruta de validación ya guardó. Un cuerpo que difiere solo en transactionTimestamp reproduce la decisión guardada.

Las solicitudes de reglas y límites, y los filtros de lista scheme y transaction_type, también devuelven 0540 cuando los dos nombres tienen valores distintos.

Errores del seam de reservas

---

Tracer devuelve estos códigos al ledger de Midaz en el seam gRPC de reservas. La API HTTP de Tracer no los devuelve. Un cliente de la API de Ledger recibe códigos de Midaz en su lugar. Consulta la lista de errores de Midaz.

code	title	message
0476	ID de transacción de reserva obligatorio	Reserva: transactionId es obligatorio.
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.
0533	Reserva ya liquidada	La reserva de esta transacción ya se liquidó y no se puede reservar de nuevo.
0534	Tenant inactivo para reservas	El tenant no está aprovisionado o no está activo para reservas.

Errores de capacidad 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. Una solicitud que pasa de REQUEST_TIMEOUT_SEC devuelve HTTP 504 con el código 0564. Una base de datos que rechaza la conexión devuelve HTTP 503 con el código 0567.

Los rechazos de Access Manager incluyen los códigos AUT- de abajo. AUT-0006 y AUT-0007 devuelven HTTP 401, AUT-1020 devuelve 403, AUT-0033 devuelve 503 y AUT-1021 devuelve 504. Con multi-tenant habilitado, Tracer devuelve TENANT_MANAGER_UNAVAILABLE (503) cuando Tenant Manager no está disponible y TENANT_MANAGER_TIMEOUT (504) cuando no responde a tiempo.

code	title	message
0466	Capacidad de tenant alcanzada	Se alcanzó la capacidad del tenant; vuelve a intentarlo en breve
0564	Plazo de la solicitud superado	La solicitud no terminó dentro del tiempo permitido. Repite una escritura con la misma clave de idempotencia.
0566	Evento de auditoría no encadenado	El evento de auditoría aún no está encadenado a la cadena de hash. Vuelve a intentar en unos segundos.
0567	Dependencia no disponible	Una dependencia requerida rechazó la conexión. Vuelve a intentar en un momento.
0474	No autorizado	Al token Bearer le falta el claim ‘sub’ requerido; no se puede atribuir la identidad.
AUT-0006	Token ausente	Se debe enviar un token válido en el header de la solicitud. Incluye un token y vuelve a intentarlo.
AUT-0007	Token no válido	El token enviado está vencido, no es válido o tiene un formato incorrecto. Envía un token válido y vuelve a intentarlo.
AUT-1020	Permiso denegado	la credencial no tiene permiso para ejecutar <resource>:<action> en esta solicitud
AUT-0033	Servidor de autorización no disponible	Access Manager no decidió esta solicitud. Espera un momento y vuelve a intentarlo.
AUT-1021	Timeout del servidor de autorización	Access Manager no respondió a tiempo. Vuelve a intentarlo.
TENANT_MANAGER_UNAVAILABLE	Tenant Manager no disponible	Tenant Manager no está disponible; vuelve a intentar la solicitud más tarde
TENANT_MANAGER_TIMEOUT	Timeout de Tenant Manager	Tenant Manager no respondió a tiempo; vuelve a intentar la solicitud

Códigos solo de log

---

Tracer escribe estos códigos en sus logs. No aparecen en las respuestas de la API /v1/*. El title y el message de abajo describen cada código como referencia para el operador.

code	title	message
0436	Falló el calentamiento de la caché de reglas	Falló el calentamiento de la caché de reglas.
0465	El supervisor se está cerrando	Worker supervisor: cerrándose, rechaza crear nuevos workers de tenant.

/readyz lista una entrada por verificación: postgres, license, rule_cache (single-tenant), redis y tenant_manager (multi-tenant), y streaming cuando el streaming está habilitado. El campo error de una verificación fallida nombra una clase de falla, no un código de error. streaming es consultivo: nunca fuerza un 503.