Lista de erros do Tracer

A API do Tracer retorna os erros como um objeto de detalhes de problema conforme a RFC 9457, servido com o tipo de conteúdo 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 dos campos

type: Um URI que identifica o tipo de erro, construído como https://errors.lerian.studio/v1/ seguido do código de 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 mostram esse conteúdo na coluna message.
code: Um identificador único e estável do erro. Geralmente é uma cadeia numérica de quatro dígitos extraída do registro de erros compartilhado da plataforma (por exemplo, 0347); as falhas de autenticação são a exceção e usam a cadeia literal Unauthenticated (consulte a nota abaixo).
entityType: A entidade à qual o erro se refere (por exemplo, Rule). Presente apenas quando aplicável.
message: A razão legível por humanos, exposta textualmente como campo de nível superior. Presente apenas nas respostas 413 Payload Too Large e 504 Gateway Timeout; os demais erros o omitem.

Nos erros do lado do servidor (HTTP 5xx), title e detail são sanitizados com valores genéricos para que causas internas nunca vazem. Use code e type para identificar o erro. Nos timeouts 504, o campo de nível superior message ainda carrega a razão específica.

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 um detail que nomeia o campo e a restrição específicos; 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 respostas mantêm uma forma plana legada {"code", "title", "message"} em vez do objeto de detalhes de problema, porque são emitidas por um middleware que roda antes da camada da API. Falhas de autenticação: 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". Capacidade de tenants: o código 0466 retorna HTTP 503 com a mesma forma plana.

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	payload too large: exceeds 100KB limit
0183	Nothing to Update	No updatable fields were provided. Please include at least one field to update.
0330	Context Cancelled	Context cancelled / service unavailable.
0484	Route Not Found	The requested route does not exist. Please verify the HTTP method and path and try again.
0485	Method Not Allowed	The HTTP method is not allowed for the requested route. Please verify the method and try again.
0497	Request Header Fields Too Large	The request header fields are too large. Please reduce the size of the request headers and try again.

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 código 0143 é retornado com HTTP 413 quando o corpo de uma requisição excede o limite de 100KB nos endpoints de validação e de reservas; a razão também aparece no campo de nível superior message. O código 0497 é retornado com HTTP 431 quando os cabeçalhos da requisição são grandes demais. O código 0484 é retornado com HTTP 404 para uma rota que o serviço não serve, e o código 0485 com HTTP 405 para um método que a rota não aceita.

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 metadata

Estes erros são gerados pelo mapa metadata de uma requisição de validação (POST /v1/validations) e de uma requisição de reserva (POST /v1/reservations).

`code`	`title`	`message`
0050	Metadata Key Length Exceeded	A metadata key exceeds the maximum allowed length of 64 characters. Please use a shorter key.
0335	Metadata Entries Exceeded	Metadata entries exceed maximum of 50.
0336	Metadata Key Invalid Chars	Metadata key contains invalid characters.

Uma chave de metadata com mais de 64 caracteres, ou mais de 50 entradas de metadata em uma mesma requisição, é rejeitada com HTTP 400.

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 Asset	Asset 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.

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 /v1/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 Asset Required	Asset is required.
0417	Validation Invalid Asset	Asset 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	Gateway 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	Gateway Timeout	query timeout exceeded

Os códigos 0422 e 0433 são retornados 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 é sanitizado; a razão específica viaja no campo de nível superior message.

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.

| 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. O ciclo de /readyz sonda cinco dependências: postgres e rule_cache sempre; redis e tenant_manager apenas em modo multi-tenant (puladas caso contrário); streaming é consultiva — aparece nas verificações e métricas, mas nunca força um 503.

`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.
0493	Readyz Redis Connection Not Established	Redis readyz: connection not established.
0494	Readyz Redis Ping Failed	Redis readyz: ping failed.
0495	Readyz Tenant Manager Unavailable	Tenant_manager readyz: service unavailable.
0496	Readyz Streaming Unhealthy	Streaming readyz: producer unhealthy.

Primeiros passos

API de Validações

API de Regras

API de Limites

API de Reservas

API de Eventos de Auditoria

Tratamento de erros

Lista de erros do Tracer

Erros gerais

Erros de data e hora

Erros de paginação

Erros de metadata

Erros de expressão CEL

Erros de regras

Erros de limites

Erros de eventos de auditoria

Erros de solicitação de validação

Erros de reserva

Erros de multi-tenant e autenticação

Erros de inicialização de multi-tenant

Erros de sonda de prontidão

​Erros gerais

​Erros de data e hora

​Erros de paginação

​Erros de metadata

​Erros de expressão CEL

​Erros de regras

​Erros de limites

​Erros de eventos de auditoria

​Erros de solicitação de validação

​Erros de reserva

​Erros de multi-tenant e autenticação

​Erros de inicialização de multi-tenant

​Erros de sonda de prontidão

Erros gerais

Erros de data e hora

Erros de paginação

Erros de metadata

Erros de expressão CEL

Erros de regras

Erros de limites

Erros de eventos de auditoria

Erros de solicitação de validação

Erros de reserva

Erros de multi-tenant e autenticação

Erros de inicialização de multi-tenant

Erros de sonda de prontidão