Erros
Formato Problem Details, códigos HTTP, rejeição fiscal e X-Request-Id.
Todo erro da API sai no formato Problem Details (RFC 9457), com Content-Type: application/problem+json:
{
"type": "https://u2d.com.br/problemas/requisicao-invalida",
"title": "Requisição inválida",
"status": 400,
"detail": "Informe cst (regime normal) ou csosn (Simples Nacional)",
"instance": "/api/v1/nfe",
"campos": [
{ "campo": "itens[0].icms.cst", "mensagem": "Informe cst (regime normal) ou csosn (Simples Nacional)" }
]
}typeidentifica o erro de forma estável: o código é o último trecho (requisicao-invalida,produto-nao-contratado,idempotency-conflito...). Trate pelotypee pelostatus, não pelo texto.campos(em400 requisicao-invalida) traz o caminho JSON de cada campo inválido: campo ausente, formato ou dígito verificador errado, valor fora do enum e regra fiscal incoerente.detailresume a primeira falha.
Códigos HTTP
| Status | Significado | O que fazer |
|---|---|---|
400 | Corpo, header ou parâmetro inválido, ou XML fora do leiaute (XSD) | Corrija a requisição; não repita igual. |
401 | Token ausente, inválido ou expirado | Gere um token novo. Veja Autenticação. |
403 | Token sem conta, conta inativa, produto não contratado ou recurso fora do plano (recurso-nao-incluido-no-plano) | Veja o type e Planos e limites; fale com o Atendimento. |
404 | Recurso inexistente ou de outro emitente/conta | Confira o id e o X-Emitente-Id. |
409 | Conflito: idempotency-conflito, cadastro duplicado, nota fora do status exigido (nfe-nao-autorizada...) | Veja o type. |
422 | Regra de negócio: emitente sem certificado, sem série, sem IE; limite de emitentes do plano (limite-emitentes-do-plano); evento recusado pela SEFAZ | Corrija o cadastro ou os dados; veja o detail. |
429 | Limite de requisições excedido | Aguarde o Retry-After. Veja Rate limit. |
502 | SEFAZ, Sefin Nacional ou ADN não responderam (sefaz-indisponivel, sefin-indisponivel) | Repita depois. |
503 | Recurso do servidor indisponível (ex.: tabela fiscal ainda não carregada) | Tente mais tarde. |
500 | Erro inesperado | Abra um chamado com o X-Request-Id. |
Rejeição fiscal não é erro HTTP
A emissão é assíncrona: o POST responde 202 antes da transmissão. Se a SEFAZ ou a Sefin recusar a nota, o erro
aparece no GET da nota (e no webhook), com status: REJEITADA ou DENEGADA e a lista
erros:
{
"status": "REJEITADA",
"erros": [{ "codigo": "539", "descricao": "Rejeição: Duplicidade de NF-e com diferença na Chave de Acesso" }]
}Na NF-e e na NFC-e, codigo é o cStat da SEFAZ. Na NFS-e, é o código da Sefin Nacional (ex.: E0312), e
U2D-LEIAUTE indica erro de leiaute detectado antes do envio.
Já os eventos síncronos (cancelamento, carta de correção, inutilização) respondem 422 com o mesmo erros quando
a SEFAZ recusa (ex.: cancelamento-rejeitado por prazo expirado).
X-Request-Id
Toda resposta traz o header X-Request-Id, que identifica a chamada nos nossos logs. Registre-o e informe-o ao
abrir um chamado no Atendimento.
Você também pode enviar o seu próprio id no header X-Request-Id (até 64 caracteres: letras, números, ., _ e
-). A API usa o seu valor e o devolve na resposta. Fora desse formato, a API gera um id novo.