Tratamento de Erros

Códigos HTTP

Toda emissão é síncrona: o POST já calcula os tributos, assina e transmite para a SEFAZ (ou provedor de NFS-e) na mesma chamada. Isso muda o que "erro" significa aqui -- e é o primeiro ponto de confusão de quem vem de uma API assíncrona.

⚠️

O código HTTP não diz se o documento foi autorizado. Ele diz só se a sua requisição foi bem-formada e autorizada. Uma rejeição da SEFAZ, um erro do provedor de NFS-e, ou uma falha do motor fiscal ainda voltam como 200 OK -- o resultado real está no campo status do corpo da resposta (AUTHORIZED / REJECTED / ERROR / PROCESSING). Trate status, não o código HTTP, como a fonte de verdade do que aconteceu com o documento.

Tabela de códigos

Código	Quando acontece
`200`	Requisição processada -- inclui o caso de sucesso (`AUTHORIZED`) e também rejeição SEFAZ/provedor ou erro interno do motor (`REJECTED`/`ERROR`). Veja o campo `status` no corpo pra saber qual dos dois.
`400`	Corpo da requisição malformado (JSON inválido) ou campo obrigatório ausente/ inválido antes mesmo de chegar no motor fiscal -- ex.: falta `emitente_documento`, `motivo` de cancelamento com menos de 15 caracteres, `chave_acesso` ausente num encerramento de MDF-e.
`401`	Bearer token ausente, inválido, expirado ou revogado.
`403`	Seu contrato não tem o produto contratado (NF-e/CT-e/MDF-e/NFS-e), ou o contribuinte informado (emitente/prestador) não está ativo nesse contrato.
`404`	Transmissão, sessão ou documento não encontrado para o seu contrato -- inclui consultar um `transmissao_id` que não existe ou não é seu.
`409`	Conflito de estado -- ex.: contribuinte sem certificado digital A1 ativo, tentar cancelar um documento que ainda não foi autorizado, sessão de emissão conjunta já num estado terminal.
`410`	Link de sessão de Emissão Conjunta expirado.
`500`	Falha interna não tratada -- raro, fora do caminho normal de emissão.

💡

422 e 429 não são usados hoje nesta API: não há rate limiting por contrato (ver Limites da API), e validação de payload que falha vira 400, não 422.

Formato do corpo de erro

Para erros de pré-validação (400/401/403/ 404/409/410), o corpo é sempre {"detail": "<mensagem>"} -- um texto simples, sem código estruturado.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "detail": "Contribuinte sem certificado digital A1 ativo."
}

Já numa resposta 200 de uma emissão que foi rejeitada ou falhou, o corpo é mais rico -- veja Erros da API pro formato completo do campo retorno_amigavel e Rejeições SEFAZ pro que vem dentro de detalhes.