> ## 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 erros do Tracer > As APIs do Tracer retornam um objeto de erro estruturado para todos os erros, a fim de simplificar o diagnóstico de problemas. O corpo da resposta é um objeto de erro estruturado com o seguinte formato: ```json theme={null} { "code":"", "title":"", "message":"" } ``` **Definições dos campos** * `code`: Um identificador único e estável do erro. É uma cadeia numérica de quatro dígitos extraída do registro de erros compartilhado da plataforma (por exemplo, `0347`). * `title`: Um resumo breve do problema. * `message`: Orientação detalhada para resolver o erro. **Validação em nível de campo** As falhas de validação de campos em nível de estrutura retornam o código `0009` com o título `Validation Error` e uma `message` que nomeia o campo e a restrição específicos; por exemplo, `transactionType must be one of [CARD WIRE PIX CRYPTO]`. Exemplos: ```json Campo obrigatório ausente theme={null} { "code":"0009", "title":"Validation Error", "message":"name is a required field" } ``` ```json Tipo de expressão inválido theme={null} { "code":"0341", "title":"Expression Type", "message":"Expression must return boolean." } ``` As falhas de autenticação não usam um código numérico do registro. Uma API key ausente ou inválida retorna HTTP 401 com `"code": "Unauthenticated"`, `"title": "Unauthorized"` e `"message": "API Key missing or invalid"`. Compare com a cadeia literal `Unauthenticated`. Um token Bearer que é analisado mas não tem o claim `sub` obrigatório retorna HTTP 401 com `"code": "0474"`. ## Erros gerais *** Estes erros podem ser retornados por qualquer endpoint da API do 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. | O código `0009` também aparece com o título `Validation Error` quando a validação em nível de campo rejeita uma requisição — veja a nota acima. ## Erros de data e 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. | ## Erros de paginação *** | `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. | ## Erros de expressão CEL *** As regras são escritas como expressões CEL (Common Expression Language). Estes erros são gerados quando uma expressão de regra é criada, atualizada ou avaliada. | `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. | ## Erros de regras *** | `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. | ## Erros de limites *** | `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. | ## Erros de eventos de auditoria *** | `code` | `title` | `message` | | :----- | :-------------------------- | :------------------------------------- | | 0381 | Audit Event Not Found | Audit event not found. | | 0382 | Invalid Audit Event Filters | Invalid audit event filter parameters. | ## Erros de solicitação de validação *** Estes erros são retornados pelos endpoints de validação de transações (`POST /validations` e as consultas de validação). | `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). | ## Erros de reserva *** Estes erros são retornados pelos endpoints de reserva de uso (`/reservations`), a superfície de duas fases de reservar / confirmar / liberar. As solicitações de reserva também podem retornar os erros gerais e de solicitação de validação listados acima. | `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. | ## Erros de multi-tenant e autenticação *** A instância retorna HTTP 503 com um cabeçalho `Retry-After` quando atinge o teto de workers por tenant e por pod; os clientes devem aguardar e tentar novamente. Um token Bearer que é analisado mas não tem o claim `sub` obrigatório é rejeitado com 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. | ## Erros de inicialização de multi-tenant *** Estes códigos aparecem apenas na inicialização do serviço, quando `MULTI_TENANT_ENABLED=true` e uma configuração obrigatória está ausente ou é incompatível. Aparecem nos logs de inicialização e impedem que o serviço inicie; nunca chegam aos consumidores da 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. | ## Erros de sonda de prontidão *** Estes códigos são expostos pelo endpoint operacional `/readyz` e pelo ciclo de vida do supervisor de workers. Aparecem no campo `error` da resposta JSON de `/readyz` — que carrega apenas o código — e não nas respostas da API `/v1/*`. O `title` e a `message` abaixo descrevem cada código como referência para o 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. |