> ## 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 com um código estável, status HTTP e mensagem, para que você possa diagnosticar problemas e encaminhá-los à equipe certa. A API do Tracer retorna erros como um objeto problem details do [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), servido com o content type `application/problem+json`: ```json theme={null} { "type": "https://errors.lerian.studio/v1/", "title": "", "status": , "detail": "", "code": "" } ``` **Definições de campos** * `type`: Uma URI que identifica o tipo do erro, construída como `https://errors.lerian.studio/v1/` seguido do código do erro. * `title`: Um resumo breve do problema. * `status`: O código de status HTTP da resposta. * `detail`: Orientação detalhada para resolver o erro. As tabelas abaixo listam esse conteúdo na coluna `message`. * `code`: Um identificador único e estável para o erro. Normalmente é uma string numérica de quatro dígitos, extraída do registro de erros compartilhado da plataforma (por exemplo, `0347`). Falhas de autenticação são a exceção e usam a string literal `Unauthenticated` (veja a nota abaixo). * `entityType`: A entidade à qual o erro se relaciona (por exemplo, `Rule`). Presente apenas quando aplicável. * `message`: O motivo legível por humanos, exposto literalmente como campo de nível superior. Presente apenas em respostas `413 Payload Too Large` e `504 Gateway Timeout`. Todos os outros erros o omitem. Para erros do lado do servidor (HTTP 5xx), `title` e `detail` trazem valores genéricos para que causas internas nunca vazem. Use `code` e `type` para identificar o erro. Em timeouts `504`, o campo `message` de nível superior ainda traz o motivo específico. **Validação em nível de campo** Falhas de validação de campo em nível de struct retornam o código `0009` com o título `Validation Error` e um `detail` que nomeia o campo específico e a restrição, por exemplo `transactionType must be one of [CARD WIRE PIX CRYPTO]`. Exemplos: ```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" } ``` Duas famílias de resposta mantêm um formato plano legado `{"code", "title", "message"}` em vez do objeto problem details. Um middleware executado antes da camada da API as emite. Falhas de autenticação: uma chave de API ausente ou inválida retorna HTTP 401 com `"code": "Unauthenticated"`, `"title": "Unauthorized"` e `"message": "API Key missing or invalid"`. Compare com a string literal `Unauthenticated`. Um token Bearer que é interpretado, mas não tem a claim `sub` obrigatória, retorna HTTP 401 com `"code": "0474"`. Capacidade do tenant: o código `0466` retorna HTTP 503 no mesmo formato plano. ## Erros gerais *** Qualquer endpoint da API do Tracer pode retornar estes erros. | `code` | `title` | `message` | | :----- | :------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0009 | Campos ausentes na requisição | Sua requisição está sem um ou mais campos obrigatórios: %v. Consulte a documentação para garantir que todos os campos necessários estejam incluídos na sua requisição. | | 0046 | Erro interno do servidor | O servidor encontrou um erro inesperado. Tente novamente mais tarde ou entre em contato com o suporte. | | 0065 | Parâmetro de rota inválido | Um ou mais parâmetros de rota estão em um formato incorreto. Verifique os seguintes parâmetros %v e garanta que atendam ao formato exigido antes de tentar novamente. | | 0082 | Parâmetro de consulta inválido | Um ou mais parâmetros de consulta estão em um formato incorreto. Verifique os seguintes parâmetros '%v' e garanta que atendam ao formato exigido antes de tentar novamente. | | 0094 | Requisição inválida | O corpo da requisição está malformado ou contém JSON inválido. Verifique a sintaxe e tente novamente. | | 0143 | Payload muito grande | payload muito grande: excede o limite de 100KB | | 0183 | Nada para atualizar | Nenhum campo atualizável foi informado. Inclua ao menos um campo para atualizar. | | 0330 | Contexto cancelado | Contexto cancelado / serviço indisponível. | | 0484 | Rota não encontrada | A rota solicitada não existe. Verifique o método HTTP e o path e tente novamente. | | 0485 | Método não permitido | O método HTTP não é permitido para a rota solicitada. Verifique o método e tente novamente. | | 0497 | Campos de header da requisição muito grandes | Os campos de header da requisição são muito grandes. Reduza o tamanho dos headers da requisição e tente novamente. | 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. Os endpoints de validação e reserva retornam o código `0143` com HTTP `413` quando o corpo da requisição excede o limite de 100KB. O motivo também aparece no campo `message` de nível superior. A API do Tracer retorna o código `0497` com HTTP `431` quando os headers da requisição são muito grandes. Ela retorna o código `0484` com HTTP `404` para um path que o serviço não atende. Ela retorna o código `0485` com HTTP `405` para um método que o path não aceita. ## Erros de data e hora *** | `code` | `title` | `message` | | :----- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------- | | 0077 | Erro de formato de data inválido | 'initialDate', 'finalDate', ou ambos, estão em um formato incorreto. Use o formato 'yyyy-mm-dd' e tente novamente. | | 0083 | Erro de intervalo de data inválido | Os campos 'initialDate' e 'finalDate' são obrigatórios e devem estar no formato 'yyyy-mm-dd'. Informe datas válidas e tente novamente. | ## Erros de paginação *** | `code` | `title` | `message` | | :----- | :------------------------------------- | :------------------------------------------------------------------------------------------------------------ | | 0080 | Limite de paginação excedido | O limite de paginação excede o máximo permitido de %v itens por página. Verifique o limite e tente novamente. | | 0081 | Ordem de classificação inválida | O campo 'sort\_order' deve ser 'asc' ou 'desc'. Informe uma ordem de classificação válida e tente novamente. | | 0331 | Limite de paginação inválido | O limite de paginação deve ser positivo. | | 0332 | Coluna de classificação inválida | A coluna de classificação não está na lista permitida. | | 0333 | Cursor inválido | Cursor de paginação inválido ou corrompido. | | 0334 | Cursor com parâmetros de classificação | Cursor e parâmetros de classificação são mutuamente exclusivos. | ## Erros de metadados *** Estes erros vêm do mapa `metadata` em uma requisição de validação (`POST /v1/validations`) e em uma requisição de reserva (`POST /v1/reservations`). | `code` | `title` | `message` | | :----- | :----------------------------------------- | :------------------------------------------------------------------------------------------------------- | | 0050 | Comprimento da chave de metadados excedido | Uma chave de metadados excede o comprimento máximo permitido de 64 caracteres. Use uma chave mais curta. | | 0335 | Entradas de metadados excedidas | As entradas de metadados excedem o máximo de 50. | | 0336 | Caracteres inválidos na chave de metadados | A chave de metadados contém caracteres inválidos. | A API retorna HTTP `400` para uma chave de metadados com mais de 64 caracteres, ou para mais de 50 entradas de metadados em uma requisição. ## Erros de expressão CEL *** Você escreve regras como expressões CEL (Common Expression Language). Estes erros aparecem durante a criação, atualização ou avaliação da expressão da regra. | `code` | `title` | `message` | | :----- | :------------------------------- | :--------------------------------------------------------------------------- | | 0340 | Sintaxe da expressão | Sintaxe CEL inválida. | | 0341 | Tipo da expressão | A expressão deve retornar um booleano. | | 0342 | Custo da expressão excedido | Limite de custo excedido (custo calculado e acima do limiar). | | 0343 | Avaliação da expressão | Erro de avaliação em tempo de execução. | | 0344 | Programa da expressão | Falha na criação do programa (fase de compilação). | | 0345 | Estimativa de custo da expressão | Falha ao estimar o custo da expressão. | | 0346 | Valor excede a precisão | O valor excede a precisão segura para avaliação float64 do CEL (máx: ±2^53). | | 0351 | Expressão não modificável | A expressão não pode ser modificada para regras que não estão em DRAFT. | ## Erros de regra *** | `code` | `title` | `message` | | :----- | :------------------------------------- | :------------------------------------------------------- | | 0347 | Regra não encontrada | Regra não encontrada pelo ID. | | 0348 | Nome da regra já existe | O nome da regra deve ser único. | | 0349 | Status de regra inválido | Transição de status de regra inválida. | | 0350 | Falha na avaliação da regra | Falha na avaliação da regra. | | 0352 | Entrada de regra nula | A entrada da regra não pode ser nula. | | 0353 | Nome da regra obrigatório | O nome da regra é obrigatório. | | 0354 | Nome da regra muito longo | O nome da regra excede o comprimento máximo (255). | | 0355 | Expressão da regra obrigatória | A expressão da regra é obrigatória. | | 0356 | Expressão da regra muito longa | A expressão da regra excede o comprimento máximo (5000). | | 0357 | Ação de regra inválida | A ação deve ser uma de \[ALLOW, DENY, REVIEW]. | | 0358 | Escopo de regra inválido | O escopo deve ter ao menos um campo definido. | | 0359 | Descrição da regra muito longa | A descrição da regra excede o comprimento máximo (1000). | | 0360 | Excesso de escopos de regra | Os escopos da regra excedem o máximo (100). | | 0437 | Cache de regras não pronto | O cache de regras não está pronto. | | 0441 | Nome da regra já existe neste contexto | O nome da regra já existe neste contexto. | ## Erros de limite *** | `code` | `title` | `message` | | :----- | :----------------------------------- | :-------------------------------------------- | | 0362 | Limite não encontrado | Limite não encontrado pelo ID. | | 0363 | Mudança de status de limite inválida | Transição de status de limite inválida. | | 0364 | Tipo de limite inválido | Tipo de limite inválido. | | 0365 | MaxAmount de limite inválido | MaxAmount deve ser positivo. | | 0366 | Ativo de limite inválido | O ativo deve ser um ISO 4217 válido. | | 0367 | Escopo de limite inválido | Falha na validação do escopo. | | 0368 | Nome do limite obrigatório | O nome do limite é obrigatório. | | 0369 | Nome do limite muito longo | O nome do limite excede o comprimento máximo. | \| 0371 | Caracteres inválidos no nome do limite | O nome do limite contém caracteres inválidos. | \| 0372 | Caracteres inválidos na descrição do limite | A descrição do limite contém caracteres inválidos. | \| 0373 | ID de limite inválido | O ID do limite é inválido ou nulo. | \| 0378 | Falha na verificação do limite | Falha na verificação do limite. | \| 0379 | Entrada de limite nula | A entrada do limite não pode ser nula. | \| 0380 | Campo imutável do limite | Não é possível modificar um campo imutável (limitType, asset). | \| 0438 | Incompatibilidade na janela de tempo do limite | ActiveTimeStart e activeTimeEnd devem estar ambos definidos ou ambos nulos. | \| 0442 | Nome do limite já existe | O nome do limite já existe. | \| 0447 | Formato de início customizado do limite inválido | Formato de customStartDate inválido, esperado RFC3339. | \| 0448 | Formato de fim customizado do limite inválido | Formato de customEndDate inválido, esperado RFC3339. | \| 0449 | Datas customizadas do limite obrigatórias | CustomStartDate e customEndDate são obrigatórios para o limitType CUSTOM. | ## Erros de evento de auditoria *** | `code` | `title` | `message` | | :----- | :--------------------------------------- | :----------------------------------------------------- | | 0381 | Evento de auditoria não encontrado | Evento de auditoria não encontrado. | | 0382 | Filtros de evento de auditoria inválidos | Parâmetros de filtro de evento de auditoria inválidos. | ## Erros de requisição de validação *** Os endpoints de validação de transação (`POST /v1/validations` e as consultas de validação) retornam estes erros. | `code` | `title` | `message` | | :----- | :------------------------------------------------- | :-------------------------------------------------------- | | 0413 | RequestId obrigatório na validação | RequestId é obrigatório. | | 0414 | Tipo de transação inválido na validação | transactionType inválido. | | 0415 | Valor não positivo na validação | O valor deve ser positivo. | | 0416 | Ativo obrigatório na validação | O ativo é obrigatório. | | 0417 | Ativo inválido na validação | O ativo deve ser um ISO 4217 válido. | | 0418 | Timestamp obrigatório na validação | O timestamp é obrigatório. | | 0419 | Timestamp futuro na validação | O timestamp não pode estar no futuro. | | 0420 | Conta obrigatória na validação | A conta é obrigatória. | | 0421 | Timestamp muito antigo na validação | O timestamp está muito distante no passado. | | 0422 | Tempo limite do gateway | tempo limite de validação | | 0423 | SegmentId obrigatório na validação | SegmentId é obrigatório quando segment é informado. | | 0424 | PortfolioId obrigatório na validação | PortfolioId é obrigatório quando portfolio é informado. | | 0425 | SubType muito longo na validação | SubType excede o comprimento máximo de 50 caracteres. | | 0426 | Tipo de conta inválido na validação | Account.type deve ser checking, savings ou credit. | | 0427 | Status de conta inválido na validação | Account.status deve ser active, suspended ou closed. | | 0428 | Categoria de estabelecimento inválida na validação | Merchant.category deve ser um código MCC de 4 dígitos. | | 0429 | País do estabelecimento inválido na validação | Merchant.country deve ser ISO 3166-1 alpha-2. | | 0430 | Merchant.id obrigatório na validação | Merchant.id é obrigatório quando merchant é informado. | | 0431 | Filtros de validação de transação inválidos | Parâmetros de filtro de validação de transação inválidos. | | 0432 | Validação de transação não encontrada | Registro de validação de transação não encontrado. | | 0433 | Tempo limite do gateway | tempo limite de consulta excedido | A API retorna os códigos `0422` e `0433` com HTTP `504 Gateway Timeout`: `0422` quando uma avaliação de validação excede seu prazo, `0433` quando uma consulta de listagem de validações excede o dela. Como em todas as respostas 5xx, `detail` traz um valor genérico. O campo `message` de nível superior traz o motivo específico. ## Erros de reserva *** Os endpoints de reserva de uso (`/reservations`) retornam estes erros. Eles formam a superfície de duas fases reserve / confirm / release. Requisições de reserva também podem retornar os erros gerais e de requisição de validação listados acima. | `code` | `title` | `message` | | :----- | :----------------------------------- | :----------------------------------------------------------------------- | | 0476 | TransactionId obrigatório na reserva | Reserva: transactionId é obrigatório. | | 0480 | Status de reserva inválido | Reserva: o status deve ser um de RESERVED, CONFIRMED, RELEASED, EXPIRED. | | 0482 | Reserva não encontrada | Reserva: reserva não encontrada. | \| 0487 | Tenant obrigatório na reserva | Reserva: o id do tenant é obrigatório na superfície de reserva multi-tenant. | ## Erros de multi-tenant e autenticação *** A instância retorna HTTP 503 com um header `Retry-After` quando atinge o limite de workers de tenant por pod. Os clientes devem aplicar backoff e tentar novamente. Um token Bearer que é interpretado, mas não tem a claim `sub` obrigatória, retorna HTTP 401. | `code` | `title` | `message` | | :----- | :---------------------------- | :-------------------------------------------------------------------------------------- | | 0466 | Capacidade do tenant atingida | capacidade do tenant atingida; tente novamente em breve | | 0474 | Não autorizado | O token Bearer está sem a claim 'sub' obrigatória; a identidade não pode ser atribuída. | ## Erros de inicialização 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. Eles aparecem nos logs de inicialização e impedem que o serviço inicie. Eles nunca chegam aos consumidores da API `/v1/*`. | `code` | `title` | `message` | | :----- | :---------------------------------- | :--------------------------------------------------------------------------------------- | | 0451 | MTConfig obrigatório | Configuração multi-tenant: cfg é obrigatório. | | 0452 | MTLogger obrigatório | Configuração multi-tenant: logger é obrigatório. | | 0453 | MTURLRequired | MULTI\_TENANT\_URL deve ser definido quando MULTI\_TENANT\_ENABLED=true. | | 0454 | MTURLInvalid | MULTI\_TENANT\_URL deve ser uma URL absoluta válida com scheme e host. | | 0455 | MTService APIKey obrigatório | MULTI\_TENANT\_SERVICE\_API\_KEY deve ser definido quando MULTI\_TENANT\_ENABLED=true. | | 0456 | MTRedis Host obrigatório | MULTI\_TENANT\_REDIS\_HOST deve ser definido quando MULTI\_TENANT\_ENABLED=true. | | 0457 | MTPlugin Auth obrigatório | MULTI\_TENANT\_ENABLED=true requer PLUGIN\_AUTH\_ENABLED=true. | | 0458 | Conflito de validação MTAPIKey Only | MULTI\_TENANT\_ENABLED=true é incompatível com API\_KEY\_ENABLED\_ONLY\_VALIDATION=true. | ## Erros de readiness probe *** O endpoint operacional `/readyz` e o ciclo de vida do worker-supervisor expõem estes códigos. Eles aparecem no campo `error` da resposta JSON de `/readyz` (que traz apenas o código), não nas respostas da API `/v1/*`. O `title` e o `message` abaixo descrevem cada código como referência para operadores. O ciclo de `/readyz` verifica cinco dependências. Ele sempre verifica `postgres` e `rule_cache`. Ele verifica `redis` e `tenant_manager` apenas no modo multi-tenant, e os ignora caso contrário. `streaming` é consultivo. Ele aparece nas checagens e métricas, mas nunca força um 503. | `code` | `title` | `message` | | :----- | :--------------------------------------------- | :---------------------------------------------------------------------- | | 0436 | Falha no warm-up do cache de regras | Falha no warm-up do cache de regras. | | 0459 | Conexão do Postgres não estabelecida no readyz | Readyz do Postgres: conexão não estabelecida. | | 0460 | Falha na conexão do Postgres no readyz | Readyz do Postgres: falha na conexão. | | 0461 | Falha no ping do Postgres no readyz | Readyz do Postgres: falha no ping. | | 0462 | Dependências não saudáveis no readyz | Agregado de /readyz: uma ou mais dependências não saudáveis. | | 0463 | Cache não pronto no readyz | Readyz do rule\_cache: cache não pronto. | | 0464 | Cache desatualizado no readyz | Readyz do rule\_cache: dados do cache desatualizados. | | 0465 | Supervisor encerrando | Worker supervisor: encerrando, recusando criar novos workers de tenant. | | 0493 | Conexão do Redis não estabelecida no readyz | Readyz do Redis: conexão não estabelecida. | | 0494 | Falha no ping do Redis no readyz | Readyz do Redis: falha no ping. | | 0495 | Tenant manager indisponível no readyz | Readyz do tenant\_manager: serviço indisponível. | | 0496 | Streaming não saudável no readyz | Readyz do streaming: produtor não saudável. |