Atendimento

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)" }
  ]
}
  • type identifica o erro de forma estável: o código é o último trecho (requisicao-invalida, produto-nao-contratado, idempotency-conflito...). Trate pelo type e pelo status, não pelo texto.
  • campos (em 400 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. detail resume a primeira falha.

Códigos HTTP

StatusSignificadoO que fazer
400Corpo, header ou parâmetro inválido, ou XML fora do leiaute (XSD)Corrija a requisição; não repita igual.
401Token ausente, inválido ou expiradoGere um token novo. Veja Autenticação.
403Token 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.
404Recurso inexistente ou de outro emitente/contaConfira o id e o X-Emitente-Id.
409Conflito: idempotency-conflito, cadastro duplicado, nota fora do status exigido (nfe-nao-autorizada...)Veja o type.
422Regra de negócio: emitente sem certificado, sem série, sem IE; limite de emitentes do plano (limite-emitentes-do-plano); evento recusado pela SEFAZCorrija o cadastro ou os dados; veja o detail.
429Limite de requisições excedidoAguarde o Retry-After. Veja Rate limit.
502SEFAZ, Sefin Nacional ou ADN não responderam (sefaz-indisponivel, sefin-indisponivel)Repita depois.
503Recurso do servidor indisponível (ex.: tabela fiscal ainda não carregada)Tente mais tarde.
500Erro inesperadoAbra 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.

Nesta página