Erros e status HTTP

Dois formatos de erro

A API tem dois formatos de erro. É herança das duas partes do produto, e o contrato está congelado: os dois continuam como estão.

Rotas	Formato	Content-Type
/v1/nfse, /v1/lotes, /v1/webhooks, /v1/eventos	problem+json, com codigo estável	application/problem+json
/v1/account, /v1/usage, /v1/companies, /v1/documents, /v1/servicos, /v1/municipios	Formato do NestJS	application/json

problem+json (emissão, lote, webhooks e eventos):

{
  "type": "https://sudrel.com.br/docs/erros/referencia_duplicada",
  "codigo": "referencia_duplicada",
  "codigo_oficial": null,
  "campo": "/referencia",
  "mensagem": "Já existe uma nota com esta referência nesta empresa.",
  "correcao": "Consulte a nota existente em GET /v1/nfse/9d2f0c1e-3a4b-4c5d-8e9f-0a1b2c3d4e5f. Se quiser emitir outra nota, use outra referência.",
  "retentavel": false,
  "nfse_id": "9d2f0c1e-3a4b-4c5d-8e9f-0a1b2c3d4e5f",
  "requisicao_id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
}

Campo	Para que serve
codigo	Estável. É nele que o seu código decide.
codigo_oficial	Código do Sistema Nacional (ex.: E0240), quando o erro vem de uma regra dele.
campo	JSON Pointer do campo com problema no seu corpo (ex.: /tomador/documento).
mensagem	Texto para gente. Pode mudar de redação; não compare.
correcao	O que fazer.
retentavel	true: repetir a MESMA requisição pode dar certo. false: corrija antes.
requisicao_id	O mesmo valor do cabeçalho X-Request-Id. Procure por ele em Integrações › Log da API.
erros	Em 422 validacao: todos os erros de uma vez, cada um com os campos acima.
itens	Em 412 empresa_nao_pronta: a prontidão inteira.
nfse_id, nfse	Em 409 referencia_duplicada (só nfse_id) e nos 422 nfse_rejeitada e falha_transmissao (a nota inteira em nfse).

Não há title, status, detail nem instance: o status está na resposta HTTP, e o codigo diz o resto.

Formato do NestJS (conta, consumo, empresas, documentos, NBS, município):

{ "statusCode": 404, "message": "Empresa não encontrada nesta conta.", "error": "Not Found" }

message pode ser uma string ou uma lista de strings (erro de validação de parâmetros, um item por campo). Aqui não há requisicao_id no corpo: use o cabeçalho X-Request-Id.

Status HTTP

Status	Significa	O que fazer
200	OK	Ler o corpo.
201	Criado. Em POST /v1/nfse: nota autorizada.	Seguir.
202	Aceito, ainda em andamento (nota transmitindo, lote em validação). Não é erro.	Acompanhar por webhook ou GET. Não repetir a criação.
204	Removido.	Nada.
400	Parâmetro de consulta inválido (parametro_invalido), ou parâmetro desconhecido nas rotas de documentos.	Corrigir a chamada.
401	Chave ausente, inválida ou revogada (nao_autenticado).	Conferir o cabeçalho Authorization e a chave.
403	A chave não pode fazer isto: restrita a outra empresa (acesso_negado, chave_restrita) ou chave de teste numa operação só de produção.	Usar a chave certa.
404	Não existe nesta conta e neste ambiente.	Conferir o id e o ambiente da chave.
409	Conflito: referencia_duplicada, idempotencia_conflito, conflito, referencia_ambigua, estado que não permite a operação.	Ler codigo. Ver Idempotência.
410	cursor_vencido em /v1/eventos.	Continuar de cursor_mais_antigo.
412	empresa_nao_pronta: a empresa não pode emitir. Nada foi criado.	Resolver os itens em bloqueio de itens. Ver Prontidão.
413	Planilha acima de 20 MB em POST /v1/lotes.	Dividir a planilha.
422	O pedido foi entendido e recusado: validacao, nfse_rejeitada, falha_transmissao, cancelamento_recusado...	Ler codigo, erros, correcao.
429	Mais de 120 requisições no minuto, nesta chave.	Esperar a virada do minuto e repetir.
500	Erro nosso (erro_interno, retentavel: true).	Repetir com a mesma Idempotency-Key. Se persistir, mande o X-Request-Id ao suporte.

O 429 também tem os dois formatos: problem+json limite_de_requisicoes (retentavel: true) nas rotas de emissão, lote, webhooks e eventos, e {"message": "...", "code": "RATE_LIMITED"} nas demais. Não há cabeçalho Retry-After nem X-RateLimit-*.

Códigos (codigo) das rotas problem+json

codigo	Status	Quando
parametro_invalido	400	Filtro, data, limite ou cursor inválido
requisicao_invalida	400	Pedido malformado
nao_autenticado	401	Chave ausente, inválida ou revogada
acesso_negado	403	Chave restrita a outra empresa
chave_restrita	403	Chave restrita a uma empresa tentando administrar webhooks
nao_encontrado	404	Empresa inexistente, ou nota ainda sem XML
nfse_nao_encontrada	404	Nenhuma nota com esse id, referência ou chave de acesso
lote_nao_encontrado	404	Lote inexistente
empresa_nao_encontrada	404	empresa_id inexistente em POST /v1/lotes
referencia_duplicada	409	Já existe nota com essa referencia nesta empresa e ambiente
idempotencia_conflito	409	Mesma Idempotency-Key com outro corpo
conflito	409	A mesma Idempotency-Key ainda está em andamento
referencia_ambigua	409	A referencia existe em mais de uma empresa: informe empresa_id
nfse_sem_pdf	409	A nota ainda não tem PDF (retentavel: true)
nfse_nao_aguarda_confirmacao	409	Confirmação de nota que não está em aguardando_confirmacao
lote_sem_emissao_manual, lote_validando, lote_ja_emitido	409	POST /v1/lotes/{id}/emissao fora de hora
cursor_vencido	410	Cursor de eventos mais velho que 90 dias
empresa_nao_pronta	412	Prontidão com bloqueio
validacao	422	Corpo inválido; os detalhes estão em erros
nfse_rejeitada	422	O Sistema Nacional rejeitou a nota
falha_transmissao	422	A transmissão não pôde ser concluída
cancelamento_recusado	422	O Sistema Nacional recusou o cancelamento
planilha_obrigatoria	422	POST /v1/lotes multipart sem o arquivo
simulacao_so_no_sandbox, simulacao_invalida	422	Simulador com a chave de produção, ou cenário inexistente
reenvio_invalido, evento_nao_assinado	422	Reenvio de webhook com parâmetros errados
limite_de_requisicoes	429	Limite de requisições
erro_interno	500	Erro nosso

Dentro de erros (422 validacao) os códigos dizem qual campo e qual regra: tipo_invalido, formato_invalido, campo_desconhecido, documento_invalido, referencia_muito_longa, tomador_igual_prestador, codigo_servico_inexistente, aliquota_iss_obrigatoria, competencia_invalida, obra_obrigatoria, nbs_fora_do_servico e outros. Cada um vem com campo, mensagem e correcao; trate qualquer código novo pelo campo e pela correcao.

Rejeição do Sistema Nacional

Quando o Sistema Nacional rejeita, o 422 nfse_rejeitada traz codigo_oficial (ex.: E0039) e a nota inteira em nfse. Em nfse.rejeicao.explicacao, para os códigos que a Sudrel conhece, vem a explicação em português claro e a correção. A nota fica registrada como rejeitada: corrija e emita uma nota nova, com outra referencia.