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 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:

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

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.

Primeiros passos

API de Validações

API de Regras

API de Limites

API de Reservas

API de Eventos de Auditoria

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 de reserva

Erros de multi-tenant e autenticação

Erros de inicialização multi-tenant

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 de reserva

​Erros de multi-tenant e autenticação

​Erros de inicialização multi-tenant

​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 de reserva

Erros de multi-tenant e autenticação

Erros de inicialização multi-tenant

Erros de readiness probe