> ## 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 para todos los errores, con el fin de simplificar el diagnóstico de problemas.

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

```json theme={null}
{
   "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:

<CodeGroup>
  ```json Falta un campo obligatorio theme={null}
  {
     "code":"0009",
     "title":"Validation Error",
     "message":"name is a required field"
  }
  ```

  ```json Tipo de expresión inválido theme={null}
  {
     "code":"0341",
     "title":"Expression Type",
     "message":"Expression must return boolean."
  }
  ```
</CodeGroup>

<Note>
  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"`.
</Note>

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