Erros e códigos de resposta

Códigos HTTP

HTTP	Quando	O que fazer
`200 / 201`	Sucesso (201 = upsert criou)	—
`202`	Job aceito (emissão/eventos)	Acompanhar pelo `jobId`
`400`	Payload inválido	Corrigir o campo apontado (ver formato abaixo)
`401`	API key ausente/inválida/revogada	Conferir o header `X-Api-Key`
`402`	Recurso/cota não disponível no plano (ex.: Free — 3 NF-e/dia e 5 DC-e/dia)	Upgrade do plano no portal
`404`	Recurso inexistente na sua empresa	Conferir identificador/chave
`409`	Conflito (ex.: consulta DF-e na guarda de 1 h)	Aguardar/tratar a condição
`422`	A SEFAZ rejeitou a operação	Ver código da rejeição na mensagem
`429`	Rate limit	Esperar `Retry-After` segundos
`500`	Erro interno	Retentar com backoff; persistindo, suporte

Formato dos erros (problem details)

Erros 400/422 seguem o RFC 9457 com os campos por nome em errors:

{
  "title": "Um ou mais erros de validação ocorreram.",
  "status": 400,
  "errors": {
    "ncm": ["NCM deve ter 8 dígitos."]
  }
}

Falhas de job (assíncronas)

Validações que dependem da SEFAZ aparecem no job, não no POST. Job com status: "Falha" traz o motivo em erro — incluindo o código de rejeição da SEFAZ quando for o caso:

{ "status": "Falha", "erro": "Rejeição 778: Informado NCM inexistente" }

Rejeições comuns e correções estão na Central de Ajuda → Solução de problemas. As que mais aparecem em integrações:

Rejeição	Causa típica na integração
204 / 539	Reenvio sem `referenciaExterna` → duplicidade. Use sempre a referência.
778	NCM inválido no cadastro do produto
693	Alíquota errada na matriz de impostos
217	Evento sobre chave inexistente (ambiente trocado: homologação × produção?)

Limite de plano (`402`)

Conta Free que atinge a cota diária (3 notas em produção) recebe 402 na criação do job de emissão. Planos pagos não bloqueiam — o excedente é faturado. Homologação nunca bloqueia.

Boas práticas de resiliência