Openi DeveloperDeveloper
Guia de integração

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" }
  ]
}
CampoConteúdo
titleNome do status HTTP
statusCódigo HTTP, igual ao da resposta
detailO que deu errado, em inglês
errorsSó 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

StatusQuando
400O corpo não é JSON válido
401Chave de API ausente, inválida ou revogada
403A chave não tem o escopo exigido, ou o tenant está suspenso
404O recurso não existe ou pertence a outro tenant
409Conflito 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
413Corpo acima do limite (1 MiB, ou 12 MiB na criação de ingestão)
422Validação: campo obrigatório ausente, campo desconhecido, valor fora do intervalo, regra que não compila contra os datasets, filtro inválido
500Erro 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:

RecursoOnde verEvento
Ingestãostatus: "failed", error e errors_report_url em GET /v1/ingestions/{id}ingestion.failed
Jobstatus: "failed" e error em GET /v1/jobs/{id}job.failed
Entrega de webhooklast_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."
}

On this page