Lista de erros do Tracer

A API do Tracer retorna erros como um objeto problem details do RFC 9457, servido com o content type application/problem+json:

{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": <http_status>,
   "detail": "<error_message>",
   "code": "<error_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.
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.

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:

{
   "type": "https://errors.lerian.studio/v1/0009",
   "title": "Validation Error",
   "status": 400,
   "detail": "name is a required field",
   "code": "0009"
}

{
   "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. 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.
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 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.
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, 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.

`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 `<resource>:<action>` 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.

Primeiros passos

API de Validações

API de Regras

API de Limites

API de Eventos de Auditoria

API de Dashboards

Tratamento de erros

Eventos

Lista de erros do Tracer

Erros gerais

Erros de data e hora

Erros de paginação

Erros de metadados

Erros de expressão CEL

Erros de regra

Erros de limite

Erros de evento de auditoria

Erros de requisição de validação

Erros do elo de reserva

Erros de capacidade e autenticação

Erros de readiness probe

​Erros gerais

​Erros de data e hora

​Erros de paginação

​Erros de metadados

​Erros de expressão CEL

​Erros de regra

​Erros de limite

​Erros de evento de auditoria

​Erros de requisição de validação

​Erros do elo de reserva

​Erros de capacidade e autenticação

​Erros de readiness probe

Erros gerais

Erros de data e hora

Erros de paginação

Erros de metadados

Erros de expressão CEL

Erros de regra

Erros de limite

Erros de evento de auditoria

Erros de requisição de validação

Erros do elo de reserva

Erros de capacidade e autenticação

Erros de readiness probe