Erros
Formato das respostas de erro, códigos HTTP e falhas de processamento assíncrono.
Formato
Toda resposta de erro usa Content-Type: application/problem+json:
{
"title": "Unprocessable Entity",
"status": 422,
"detail": "records do not match the dataset schema",
"errors": [
{ "location": "body.records[3].valor", "message": "required field is missing" },
{ "location": "body.records[7].cnpj", "message": "field is not in the dataset schema" }
]
}| Campo | Conteúdo |
|---|---|
title | Nome do status HTTP |
status | Código HTTP, igual ao da resposta |
detail | O que deu errado, em inglês |
errors | Só em erros de validação: um item por problema, com location (onde), message (o quê) e às vezes value (o valor recebido) |
location começa pela parte da requisição: body., query., path. ou header.. Em regras e workflows, aponta para o item da definição (body.definition.matchers[2].expr). Os problemas encontrados vêm todos na mesma resposta, e não só o primeiro. A exceção é a validação de registros inline, que para nos 50 primeiros.
Códigos HTTP
| Status | Quando |
|---|---|
400 | O corpo não é JSON válido |
401 | Chave de API ausente, inválida ou revogada |
403 | A chave não tem o escopo exigido, ou o tenant está suspenso |
404 | O recurso não existe ou pertence a outro tenant |
409 | Conflito com o estado atual: nome de dataset, ruleset ou workflow já usado; Idempotency-Key usada em outro dataset; transição de match inválida (ex.: confirmar um match que não é possible); job que já terminou; registro já conciliado no ruleset |
413 | Corpo acima do limite (1 MiB, ou 12 MiB na criação de ingestão) |
422 | Validação: campo obrigatório ausente, campo desconhecido, valor fora do intervalo, regra que não compila contra os datasets, filtro inválido |
500 | Erro inesperado no Nexus. Repita a chamada; se persistir, fale com o suporte com o horário e o endpoint |
Erros 4xx não mudam nada no servidor: corrija a requisição antes de repetir. Ingestões com Idempotency-Key podem ser repetidas com segurança depois de um 5xx ou de um timeout.
Falhas assíncronas
Ingestões e jobs são processados fora da requisição. A criação responde 202 e a falha aparece depois, no próprio recurso e no webhook correspondente:
| Recurso | Onde ver | Evento |
|---|---|---|
| Ingestão | status: "failed", error e errors_report_url em GET /v1/ingestions/{id} | ingestion.failed |
| Job | status: "failed" e error em GET /v1/jobs/{id} | job.failed |
| Entrega de webhook | last_error e attempt_history em GET /v1/webhook-deliveries/{id} | — |
Essas mensagens vêm em português e dizem o que fazer em seguida. Exemplo de entrega que falhou:
{
"status": "pending",
"attempts": 2,
"last_status_code": 500,
"last_error": "O endpoint respondeu HTTP 500, e a entrega só conta como recebida com status 2xx. Confira os logs do endpoint; depois de corrigir, as próximas tentativas são aceitas e entregas que já falharam podem ser reenviadas."
}
