Tipos de retorno de status das requisições HTTPS
Durante o processo de emissão de NFC-e via API, você recebe um código de status HTTP na resposta do POST /v2/companies/{companyId}/consumerinvoices. Esse código informa se a requisição foi aceita — não se a nota foi emitida.
A emissão de NFC-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.
O mapeamento de código HTTP é o mesmo de NF-e:
| Código status | Significado do status | Significado para a NFE.io | Ação para solucionar |
|---|---|---|---|
| 200 | Requisição aceita | A NFC-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 NFC-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 NFC-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 NFC-e pela chave de acesso ou pelo CPF/CNPJ do consumidor antes de reenviar, para evitar duplicidade |