Skip to main content
A API usa códigos de status HTTP para indicar o resultado de cada requisição. Respostas de sucesso (2xx) trazem o recurso criado, atualizado ou consultado. Respostas de erro trazem uma mensagem descrevendo o problema no corpo — consulte o endpoint específico na Referência da API para o formato exato do corpo de erro daquela chamada.

​
Códigos HTTP documentados hoje

​
Como tratar

  1. Trate 400 como definitivo para aquela requisição: corrija os dados antes de tentar de novo. Reenviar sem alterar o payload provavelmente resulta no mesmo erro.
  2. Trate 403 como um problema de configuração: confira se a chave está correta e se pertence ao ambiente (sandbox ou produção) que você está chamando. Veja Autenticação.
  3. Trate 429 com espera e retry — nunca insista imediatamente. Veja Rate limit para um exemplo de backoff.
  4. Lembre-se que 2xx na emissão não é autorização. Para NF-e, NFC-e e NFS-e, a emissão é assíncrona: um 2xx confirma que a solicitação foi aceita para processamento, não que a nota foi autorizada pela SEFAZ ou prefeitura. Acompanhe o resultado real por webhook ou consulta de status.

​
Rejeições fiscais

Erros de validação da própria SEFAZ ou prefeitura (ex.: CFOP incompatível, NCM inválido) não são o mesmo que um 400 da API — a requisição de emissão pode retornar 2xx e, ainda assim, a nota ser rejeitada de forma assíncrona. Quando isso acontece, a nota fica com o status rejected e o motivo da rejeição vem no objeto processingDetail da nota, nos campos code e message (rejeições geradas pela própria Spedy usam o prefixo SPD no code). Leia esse objeto consultando a nota ou pelo evento de webhook. Veja a lista de rejeições e como tratá-las em Erros e rejeições SEFAZ.