Skip to main content

​
Tratamento de Erros

A Engine API retorna erros padronizados em JSON para facilitar o diagnóstico e tratamento.

​
Formato de erro

{
  "statusCode": 400,
  "message": "CNPJ do destinatário inválido",
  "error": "Bad Request",
  "details": {
    "field": "destinatario.cnpj",
    "value": "123",
    "rule": "Deve ter 14 dígitos"
  }
}

​
Códigos HTTP

CódigoSignificadoQuando acontece
200✅ SucessoOperação realizada com sucesso
201✅ CriadoRecurso criado (empresa, webhook)
400❌ Bad RequestJSON inválido, campos faltando
401🔒 Não autorizadoToken JWT inválido ou expirado
403🚫 ProibidoSem permissão para este recurso
404🔍 Não encontradoIssuer, nota ou recurso não existe
409⚠️ ConflitoNota já emitida, CNPJ já cadastrado
422❌ Erro fiscalSEFAZ rejeitou o documento
429🐢 Rate limitMuitas requisições, aguarde
500💥 Erro internoBug no servidor (nos reporte!)

​
Erros fiscais (422)

Quando a SEFAZ rejeita um documento, o erro 422 contém os detalhes da rejeição: 
{
  "statusCode": 422,
  "message": "Nota rejeitada pela SEFAZ",
  "error": "Unprocessable Entity",
  "rejection": {
    "code": "539",
    "description": "Duplicidade de NF-e, com diferença na Chave de Acesso",
    "accessKey": "35260211222333000144550010000000011000000019"
  }
}

​
Erros comuns e soluções

Causa: Token tem validade de 24h e expirou. Solução: Faça login novamente em POST /auth/login.
Causa: Já existe uma NFe com esse número/série para esse CNPJ. Solução: Consulte a nota existente ou use o próximo número disponível.
Causa: O XML gerado não está conforme o schema da SEFAZ. Solução: Verifique se todos os campos obrigatórios estão preenchidos corretamente.
Causa: A empresa não tem certificado A1 cadastrado. Solução: Faça upload do certificado em POST /companies/{id}/certificate.
Causa: O servidor da SEFAZ está indisponível. Solução: Tente novamente em alguns minutos. A Engine API faz retry automático.

​
Lista de rejeições SEFAZ

Para uma lista completa de todos os códigos de rejeição da SEFAZ, consulte a tabela oficial da SEFAZ.