> ## 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. # 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](https://www.rfc-editor.org/rfc/rfc9457), servido con el tipo de contenido `application/problem+json`: ```json theme={null} { "type": "https://errors.lerian.studio/v1/", "title": "", "status": , "detail": "", "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: ```json Missing required field theme={null} { "type": "https://errors.lerian.studio/v1/0009", "title": "Validation Error", "status": 400, "detail": "name is a required field", "code": "0009" } ``` ```json Invalid expression type theme={null} { "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. | \| 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. | \| 0373 | ID de límite no válido | El ID del límite no es válido o es nulo. | \| 0378 | Falló la verificación del límite | Falló la verificación del límite. | \| 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). | \| 0438 | Discrepancia en la ventana de tiempo del límite | ActiveTimeStart y activeTimeEnd deben estar ambos definidos o ambos ser nulos. | \| 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. | ## 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. |