Erros HTTP — NFS-e Inbound
Formato do corpo de erro
{ "errors": [ { "code": 404, "message": "string" } ] }
Códigos
| Status | Significado | Ação |
|---|---|---|
200 | OK | — |
201 | Criado (cadastro de empresa) | — |
202 | Aceito (operação assíncrona: manifestação, reprocess) | Acompanhe por GET ou webhook |
302 | Redirect para URL assinada (XML/PDF) | Siga o Location |
400 | Requisição inválida (ex.: chave malformada) | Corrija o payload |
401 | Não autenticado | Confira a API Key |
403 | Sem permissão (ex.: NFSeDist ausente, ou falta o papel Management nos endpoints de manutenção notifications/statistics/reactivate) | Use credencial com o papel correto |
404 | Não encontrado | Verifique companyId/chave |
409 | Conflito (ex.: empresa já cadastrada; manifestação Pending duplicada) | Trate como idempotente |
400 | Campos obrigatórios faltando (ex.: rejeição sem reasonCode) | Complete os campos obrigatórios |
422 | Regra de negócio violada (ex.: NSU regressivo) | Revise o significado do campo, não só o formato |
500 | Erro interno | Tente novamente; persistindo, contate o suporte |
502 | CertificateRejected — a SEFIN rejeitou o certificado da empresa | Verifique validade e se o CN corresponde ao CNPJ |
503 | Dependência indisponível: AdnUnavailable (SEFIN fora) ou CertificateLookupFailed (não foi possível verificar o certificado) | Retente. Em CertificateLookupFailed não conclua que falta certificado — a consulta é que falhou |
400 com significados distintos
O 400 cobre casos que pedem ações diferentes:
| Situação | Mensagem/error | O que fazer |
|---|---|---|
| Chave de acesso fora do formato | InvalidAccessKey | A chave da NFS-e tem 50 dígitos com dígito verificador; o DPS (42 dígitos) não serve |
startFromDate no cadastro com data futura | StartFromDate cannot be in the future... | Use uma data já passada. Um corte futuro faria todo documento capturado nascer suprimido, permanentemente |
startFromDate enviado no PUT .../details | startFromDate cannot be changed here... | O corte é definido no cadastro; alterá-lo depois é operação da área de Manutenção |
| Remover o corte de empresa com histórico liberado | — | Revogue a liberação antes |
interestedPartyRoles ausente/nulo no filtro de CT-e | — | Envie array vazio para limpar o filtro — omitir é erro proposital, para não confundir com "não informado" |
404 em documento que você sabe que existeDocumentos anteriores ao startFromDate da empresa ficam retidos enquanto o histórico não é liberado — e todas as portas de leitura os tratam como inexistentes: listagem, GET .../{id}, download de XML/PDF/JSON, reenvio de webhook, reprocesso, captura sob demanda por chave e os endpoints de manifestação por chave. É 404, e não 403, de propósito: confirmar a existência já entregaria parte do que está retido.
Para saber se é este o caso, consulte GET .../inbound/nfse/backfill — hiddenDocumentsCount diz quantos documentos estão retidos e released se o histórico já foi liberado. Veja Manutenção administrativa.
A política de retry de webhook e o TTL exato das URLs assinadas estão em confirmação — ver issue #210 e Troubleshooting.
Veja também
- Troubleshooting
- Endpoints NFS-e
- Captura sob demanda — catálogo de erros específico do
fetch-by-access-key