> ## 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 por API key usam a string literal `Unauthenticated` (veja a nota abaixo). Recusas do Access Manager e do Tenant Manager usam seus próprios códigos, incluindo os códigos de [Erros de capacidade e autenticação](#capacity-and-authentication-errors). * `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 em respostas `413 Payload Too Large` e `504 Gateway Timeout`. > [!NOTE] > > Para erros do lado do servidor (HTTP 5xx), `title` e `detail` trazem valores genéricos. As recusas do Access Manager e do Tenant Manager mantêm seus próprios `title` e `detail`. 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 `scope at index 0: scheme must be 1 to 50 characters of A-Z, 0-9, _ or - after trimming and upper-casing`. 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" } ``` > [!NOTE] > > 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. O endpoint de validação retorna 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`). | `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. | | 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 não pode ser negativo. | | 0366 | Ativo de limite inválido | O ativo deve ter de 1 a 100 letras maiúsculas. | | 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. | | 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, resetTime). | | 0438 | Incompatibilidade na janela de tempo do limite | ActiveTimeStart e activeTimeEnd devem estar ambos definidos ou ambos nulos. | | 0440 | Formato de horário do dia inválido | Formato de horário do dia inválido, esperado HH:MM. | | 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. | | 0537 | Horário de reinício do limite não permitido | ResetTime só é permitido para limitType DAILY, WEEKLY ou MONTHLY. | | 0538 | Horário de reinício do limite dentro da janela | ResetTime não deve cair dentro da janela de tempo ativa (pode ser igual a activeTimeStart ou activeTimeEnd). | ## 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 | scheme (ou transactionType) é obrigatório e deve ter de 1 a 50 caracteres entre A-Z, 0-9, \_ ou -, depois de remover os espaços das pontas e converter para maiúsculas | | 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 ter de 1 a 100 letras maiúsculas. | | 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 ter no máximo 256 caracteres. | | 0427 | Status de conta inválido na validação | Account.status deve ter no máximo 50 caracteres. | | 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 | | 0540 | Conflito de alias do esquema | scheme e transactionType devem ter o mesmo valor | 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. Nos dois códigos, `detail` traz um valor genérico. O campo `message` de nível superior traz o motivo específico. Requisições de regras e limites, e os filtros de listagem `scheme` e `transaction_type`, também retornam `0540` quando os dois nomes têm valores diferentes. ## Erros do elo de reserva *** O Tracer retorna estes códigos ao ledger do Midaz no elo gRPC de reserva. A API HTTP do Tracer não os retorna. Um cliente da API do Ledger recebe códigos do Midaz em vez deles. Veja a [lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md). | `code` | `title` | `message` | | :- | :- | :- | | 0476 | TransactionId obrigatório na reserva | Reserva: transactionId é obrigatório. | | 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. | | 0533 | Reserva já liquidada | A reserva desta transação já foi liquidada e não pode ser reservada de novo. | | 0534 | Tenant inativo para reservas | O tenant não está provisionado ou não está ativo para reservas. | ## Erros de capacidade 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. As recusas do Access Manager incluem os códigos `AUT-` abaixo. `AUT-0006` e `AUT-0007` retornam HTTP 401, `AUT-1020` retorna 403, `AUT-0033` retorna 503 e `AUT-1021` retorna 504. Com multi-tenant habilitado, o Tracer retorna `TENANT_MANAGER_UNAVAILABLE` (503) quando o Tenant Manager está indisponível e `TENANT_MANAGER_TIMEOUT` (504) quando ele não responde a tempo. | `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. | | AUT-0006 | Token ausente | Um token válido deve ser enviado no header da requisição. Inclua um token e tente novamente. | | AUT-0007 | Token inválido | O token enviado está expirado, inválido ou malformado. Envie um token válido e tente novamente. | | AUT-1020 | Permissão negada | a credencial não tem permissão para executar `:` nesta requisição | | AUT-0033 | Servidor de autorização indisponível | O Access Manager não decidiu esta requisição. Aguarde um momento e tente novamente. | | AUT-1021 | Tempo limite do servidor de autorização | O Access Manager não respondeu a tempo. Tente novamente. | | TENANT\_MANAGER\_UNAVAILABLE | Tenant Manager indisponível | o Tenant Manager está indisponível; tente a requisição novamente mais tarde | | TENANT\_MANAGER\_TIMEOUT | Tempo limite do Tenant Manager | o Tenant Manager não respondeu a tempo; tente a requisição novamente | ## 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 `postgres`, `rule_cache` e `streaming`. `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. | | 0496 | Streaming não saudável no readyz | Readyz do streaming: produtor não saudável. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.