Lista de errores de Tracer

El cuerpo de la respuesta es un objeto de error estructurado con la siguiente forma:

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

Definiciones de los campos

code: Un identificador único y estable del error. Es una cadena numérica de cuatro dígitos tomada del registro de errores compartido de la plataforma (por ejemplo, 0347).
title: Un resumen breve del problema.
message: Orientación detallada para resolver el error.

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

{
   "code":"0009",
   "title":"Validation Error",
   "message":"name is a required field"
}

{
   "code":"0341",
   "title":"Expression Type",
   "message":"Expression must return boolean."
}

Los fallos de autenticación no usan un código numérico del registro. Una API key ausente o inválida devuelve HTTP 401 con "code": "Unauthenticated", "title": "Unauthorized" y "message": "API Key missing or invalid". Compara con la cadena literal Unauthenticated. Un token Bearer que se analiza pero carece del claim sub requerido devuelve HTTP 401 con "code": "0474".

Errores generales

Estos errores puede devolverlos cualquier endpoint de la API de Tracer.

`code`	`title`	`message`
0009	Missing Fields in Request	Your request is missing one or more required fields: %v. Please refer to the documentation to ensure all necessary fields are included in your request.
0046	Internal Server Error	The server encountered an unexpected error. Please try again later or contact support.
0065	Invalid Path Parameter	One or more path parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again.
0082	Invalid Query Parameter	One or more query parameters are in an incorrect format. Please check the following parameters ‘%v’ and ensure they meet the required format before trying again.
0094	Bad Request	The request body is malformed or contains invalid JSON. Please verify the syntax and try again.
0143	Payload Too Large	The request payload exceeds the maximum allowed size of 64KB.
0183	Nothing to Update	No updatable fields were provided. Please include at least one field to update.
0330	Context Cancelled	Context cancelled / service unavailable.

El código 0009 también aparece con el título Validation Error cuando la validación a nivel de campo rechaza una solicitud — consulta la nota anterior.

Errores de fecha y hora

`code`	`title`	`message`
0077	Invalid Date Format Error	The ‘initialDate’, ‘finalDate’, or both are in the incorrect format. Please use the ‘yyyy-mm-dd’ format and try again.
0083	Invalid Date Range Error	Both ‘initialDate’ and ‘finalDate’ fields are required and must be in the ‘yyyy-mm-dd’ format. Please provide valid dates and try again.

Errores de paginación

`code`	`title`	`message`
0080	Pagination Limit Exceeded	The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again.
0081	Invalid Sort Order	The ‘sort_order’ field must be ‘asc’ or ‘desc’. Please provide a valid sort order and try again.
0331	Pagination Limit Invalid	Pagination limit must be positive.
0332	Invalid Sort Column	Sort column not in allowed list.
0333	Invalid Cursor	Invalid or corrupted pagination cursor.
0334	Cursor With Sort Params	Cursor and sort parameters are mutually exclusive.

Errores de expresión CEL

Las reglas se escriben como expresiones CEL (Common Expression Language). Estos errores se generan cuando una expresión de regla se crea, se actualiza o se evalúa.

`code`	`title`	`message`
0340	Expression Syntax	Invalid CEL syntax.
0341	Expression Type	Expression must return boolean.
0342	Expression Cost Exceeded	Cost limit exceeded (cost computed and above threshold).
0343	Expression Evaluation	Runtime evaluation error.
0344	Expression Program	Program creation failed (compilation phase).
0345	Expression Cost Estimation	Failed to estimate expression cost.
0346	Amount Exceeds Precision	Amount exceeds safe precision for CEL float64 evaluation (max: ±2^53).
0351	Expression Not Modifiable	Expression cannot be modified for non-DRAFT rules.

Errores de reglas

`code`	`title`	`message`
0347	Rule Not Found	Rule not found by ID.
0348	Rule Name Already Exists	Rule name must be unique.
0349	Rule Invalid Status	Invalid rule status transition.
0350	Rule Evaluation Failed	Rule evaluation failed.
0352	Rule Nil Input	Rule input cannot be nil.
0353	Rule Name Required	Rule name is required.
0354	Rule Name Too Long	Rule name exceeds max length (255).
0355	Rule Expression Required	Rule expression is required.
0356	Rule Expression Too Long	Rule expression exceeds max length (5000).
0357	Rule Invalid Action	Action must be one of [ALLOW, DENY, REVIEW].
0358	Rule Invalid Scope	Scope must have at least one field set.
0359	Rule Description Too Long	Rule description exceeds max length (1000).
0360	Rule Scopes Too Many	Rule scopes exceed maximum (100).
0437	Rule Cache Not Ready	Rule cache is not ready.
0441	Rule Name Already Exists In Ctx	Rule name already exists in this context.

Errores de límites

`code`	`title`	`message`
0362	Limit Not Found	Limit not found by ID.
0363	Limit Invalid Status Change	Invalid limit status transition.
0364	Limit Invalid Type	Invalid limit type.
0365	Limit Invalid Max Amount	MaxAmount must be positive.
0366	Limit Invalid Currency	Currency must be valid ISO 4217.
0367	Limit Invalid Scope	Scope validation failed.
0368	Limit Name Required	Limit name is required.
0369	Limit Name Too Long	Limit name exceeds max length.
0370	Limit Already Deleted	Limit is already in DELETED state.
0371	Limit Name Invalid Chars	Limit name contains invalid characters.
0372	Limit Description Invalid Chars	Limit description contains invalid characters.
0373	Limit Invalid ID	Limit ID is invalid or nil.
0378	Limit Check Failed	Limit check failed.
0379	Limit Nil Input	Limit input cannot be nil.
0380	Limit Immutable Field	Cannot modify immutable field (limitType, currency).
0438	Limit Time Window Mismatch	ActiveTimeStart and activeTimeEnd must both be set or both be nil.
0442	Limit Name Already Exists	Limit name already exists.
0447	Limit Invalid Custom Start Format	Invalid customStartDate format, expected RFC3339.
0448	Limit Invalid Custom End Format	Invalid customEndDate format, expected RFC3339.
0449	Limit Custom Dates Required	CustomStartDate and customEndDate required for CUSTOM limitType.

Errores de eventos de auditoría

`code`	`title`	`message`
0381	Audit Event Not Found	Audit event not found.
0382	Invalid Audit Event Filters	Invalid audit event filter parameters.

Errores de solicitud de validación

Estos errores los devuelven los endpoints de validación de transacciones (POST /validations y las consultas de validación).

`code`	`title`	`message`
0413	Validation Request IDRequired	RequestId is required.
0414	Validation Invalid Transaction Type	Invalid transactionType.
0415	Validation Amount Non Positive	Amount must be positive.
0416	Validation Currency Required	Currency is required.
0417	Validation Invalid Currency	Currency must be valid ISO 4217.
0418	Validation Timestamp Required	Timestamp is required.
0419	Validation Timestamp Future	Timestamp cannot be in the future.
0420	Validation Account Required	Account is required.
0421	Validation Timestamp Past	Timestamp is too far in the past.
0422	Validation Timeout	Validation timeout.
0423	Validation Segment IDRequired	SegmentId is required when segment is provided.
0424	Validation Portfolio IDRequired	PortfolioId is required when portfolio is provided.
0425	Validation Sub Type Too Long	SubType exceeds maximum length of 50 characters.
0426	Validation Invalid Account Type	Account.type must be checking, savings, or credit.
0427	Validation Invalid Account Status	Account.status must be active, suspended, or closed.
0428	Validation Invalid Merchant Category	Merchant.category must be 4-digit MCC code.
0429	Validation Invalid Merchant Country	Merchant.country must be ISO 3166-1 alpha-2.
0430	Validation Merchant IDRequired	Merchant.id is required when merchant is provided.
0431	Invalid Transaction Validation Filters	Invalid transaction validation filter parameters.
0432	Transaction Validation Not Found	Transaction validation record not found.
0433	List Validations Timeout	List validations query timeout (deadline exceeded).

Errores de reserva

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

`code`	`title`	`message`
0476	Reservation Transaction IDReq	Reservation: transactionId is required.
0480	Reservation Invalid Status	Reservation: status must be one of RESERVED, CONFIRMED, RELEASED, EXPIRED.
0482	Reservation Not Found	Reservation: reservation not found.
0483	Reservation Already Terminal	Reservation: reservation is already in a terminal state.
0487	Reservation Tenant Required	Reservation: tenant id is required on the multi-tenant reservation surface.

Errores de multi-tenant y autenticación

La instancia devuelve HTTP 503 con un encabezado Retry-After cuando alcanza su tope de workers por tenant y por pod; los clientes deben esperar y reintentar. Un token Bearer que se analiza pero carece del claim sub requerido se rechaza con HTTP 401.

`code`	`title`	`message`
0466	Tenant Capacity Reached	Tenant capacity reached; please retry shortly
0474	Unauthorized	Bearer token is missing the required ‘sub’ claim; identity cannot be attributed.

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 requerida o es incompatible. Aparecen en los registros de arranque e impiden que el servicio inicie; nunca llegan a los consumidores de la API /v1/*.

`code`	`title`	`message`
0451	MTConfig Required	Multi-tenant config: cfg is required.
0452	MTLogger Required	Multi-tenant config: logger is required.
0453	MTURLRequired	MULTI_TENANT_URL must be set when MULTI_TENANT_ENABLED=true.
0454	MTURLInvalid	MULTI_TENANT_URL must be a valid absolute URL with scheme and host.
0455	MTService APIKey Required	MULTI_TENANT_SERVICE_API_KEY must be set when MULTI_TENANT_ENABLED=true.
0456	MTRedis Host Required	MULTI_TENANT_REDIS_HOST must be set when MULTI_TENANT_ENABLED=true.
0457	MTPlugin Auth Required	MULTI_TENANT_ENABLED=true requires PLUGIN_AUTH_ENABLED=true.
0458	MTAPIKey Only Validation Confl	MULTI_TENANT_ENABLED=true is incompatible with API_KEY_ENABLED_ONLY_VALIDATION=true.

Errores de sonda de disponibilidad

Estos códigos los expone el endpoint operativo /readyz y el ciclo de vida del supervisor de workers. Aparecen en el campo error de la respuesta JSON de /readyz —que lleva solo el código— y no 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	Rule Cache Warm Up Failed	Rule cache warm-up failed.
0459	Readyz Pg Connection Not Established	Postgres readyz: connection not established.
0460	Readyz Pg Connection Failed	Postgres readyz: connection failed.
0461	Readyz Pg Ping Failed	Postgres readyz: ping failed.
0462	Readyz Dependencies Unhealthy	/readyz aggregate: one or more dependencies unhealthy.
0463	Readyz Cache Not Ready	Rule_cache readyz: cache not ready.
0464	Readyz Cache Stale	Rule_cache readyz: cache data stale.
0465	Supervisor Shutting Down	Worker supervisor: shutting down, refusing to spawn new tenant workers.

​Errores generales

​Errores de fecha y hora

​Errores de paginación

​Errores de expresión CEL

​Errores de reglas

​Errores de límites

​Errores de eventos 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 de sonda de disponibilidad

Errores generales

Errores de fecha y hora

Errores de paginación

Errores de expresión CEL

Errores de reglas

Errores de límites

Errores de eventos 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 de sonda de disponibilidad