Tipos de retorno de status das requisições HTTPS
Durante o processo de emissão de NF-e via API, você recebe um código de status HTTP na resposta do POST /v2/companies/{companyId}/productinvoices. Esse código informa se a requisição foi aceita — não se a nota foi emitida.
A emissão de NF-e é assíncrona
200 OK confirma que o pedido de emissão foi validado e enfileirado — não que a nota foi autorizada pela SEFAZ. O resultado fiscal real chega pelo webhook de emissão (issued_successfully, issued_error ou issued_failed), ou por consulta posterior à nota.
| Código status | Significado do status | Significado para a NFE.io | Ação para solucionar |
|---|---|---|---|
| 200 | Requisição aceita | A NF-e foi validada e enviada para a fila de emissão | Nada a ser feito — aguarde o webhook de emissão para confirmar o resultado fiscal |
| 400 | Requisição errada | Algum campo do payload não é válido | Revise o corpo enviado contra a referência da API; o corpo do erro traz o campo e a regra violada |
| 401 | Requisição não autorizada | A API Key da conta não é válida | Verifique a autenticação e se a conta está apta a emitir NF-e |
| 404 | Recurso não encontrado | A empresa ou a nota informada não existe nessa conta | Confirme o companyId/invoiceId usado na chamada |
| 409 | Conflito | A NF-e já foi registrada anteriormente (duplicidade) | Consulte a nota existente antes de reemitir — reenviar o mesmo pedido não cria uma segunda nota |
| 422 | Entidade não processável | O payload passou na validação de schema, mas fere uma regra de negócio (ex.: combinação de campos inválida para o cenário) | Revise a mensagem retornada — ela aponta a regra específica violada |
| 500 | Erro no processamento | Falha interna inesperada no serviço | Reenvie a requisição de emissão; se persistir, contate o suporte |
| 503 | Serviço indisponível | O serviço de emissão está temporariamente indisponível | Aguarde e reenvie; se persistir, contate o suporte |
| 504 | Tempo de comunicação excedido | Não foi possível confirmar o resultado da comunicação a tempo | Não há certeza se a nota foi enfileirada. Consulte a NF-e pela chave de acesso ou pelo CNPJ do destinatário antes de reenviar, para evitar duplicidade |
O que muda em relação à NFS-e
Se você já integrou com NFS-e, note duas diferenças reais, não apenas de nomenclatura:
- Não existe
408no fluxo de NF-e — o equivalente de "a resposta não chegou a tempo" é504. - A emissão de NF-e não tem um timeout de resposta fixo documentado como o de 60s da NFS-e. O
200confirma só o enfileiramento; a espera pelo resultado fiscal acontece de forma assíncrona, via webhook.