Códigos de erro e limites

Formato do erro

Toda resposta de erro da API em JSON tem o mesmo formato:

{
  "codigo": "VALIDACAO_CAMPO",
  "mensagem": "Requisição com campos inválidos. Veja os detalhes em campos.",
  "campos": [
    {
      "campo": "notaId",
      "mensagem": "Valor inválido para este campo."
    }
  ]
}

codigo é estável: use-o nas decisões do seu sistema. mensagem é texto em português para pessoas e pode mudar. campos é opcional e aponta cada campo recusado. Os formatos de cada resposta de erro, por operação, estão na referência da API.

Códigos de domínio

Código	HTTP	Quando	Ação recomendada
`TOKEN_INVALIDO`	401	Token ausente, inválido, revogado ou de emitente inativo, em qualquer rota	Confira o cabeçalho `Authorization: Bearer` e o token configurado para o ambiente. Se o token foi perdido, peça um novo token de acesso. A LideraNota executa este passo: pedir pelo WhatsApp
`VALIDACAO_CAMPO`	400	Envelope do lote inválido; `loteId` ou `notaId` fora do formato UUID; `idOperacao` da busca inválido; corpo do cancelamento, da análise fiscal ou da substituição inválido	Corrija o campo indicado em `campos` e reenvie
`LOTE_ACIMA_DO_LIMITE`	400	Lote com mais de 500 notas; nenhuma nota foi recebida	Divida o envio em lotes menores
`LOTE_NAO_ENCONTRADO`	404	Lote inexistente ou de outro emitente	Confira o `loteId` devolvido no envio e o token usado
`NOTA_NAO_ENCONTRADA`	404	Nota inexistente ou de outro emitente, na consulta, nos downloads, no cancelamento, na substituição e na análise fiscal	Confira o `id` da nota ou o `idOperacao` e o token usado; na busca por `idOperacao`, `404` quer dizer que a nota não foi recebida
`NOTA_NAO_AUTORIZADA`	409	Download de nota ainda sem XML autorizado, ou pedido de cancelamento, substituição ou análise fiscal de nota que não está `autorizada`	Download: aguarde a autorização; `rejeitada` e `pendente_intervencao` nunca têm XML. Pedidos: consulte o status; só nota `autorizada` aceita o pedido
`NOTA_EM_ESTADO_INCOMPATIVEL`	409	A nota está num estado que não admite a operação: em cancelamento, cancelada, substituída, com substituição em andamento ou com análise fiscal pendente ou indeferida. A `mensagem` diz qual	Consulte a nota e a substituta, se houver; para corrigir uma nota já substituída, substitua a substituta; com análise fiscal indeferida, procure a administração tributária do município
`ID_OPERACAO_EM_USO`	409	`nota.idOperacao` da substituição já usado por outra nota do emitente	Use um `idOperacao` novo para a substituta
`SUBSTITUICAO_NAO_PERMITIDA`	422	A substituta altera campo que a Sefin Nacional não permite alterar (`E0061` ou `E0060`), com um item por campo em `campos`; nada foi gravado	Mantenha os campos indicados iguais aos da original; se a correção exigir alterá-los, cancele e emita de novo
`MOTIVO_CANCELAMENTO_CURTO`	422	Motivo do cancelamento ou da análise fiscal com menos de 15 caracteres depois de remover os espaços das pontas	Escreva um motivo de pelo menos 15 caracteres e peça de novo
`DANFSE_INDISPONIVEL_TEMPORARIAMENTE`	503	Muitas gerações de DANFSe ao mesmo tempo	Repita a mesma chamada depois dos segundos do cabeçalho `Retry-After`; é seguro repetir
`TABELAS_OFICIAIS_INDISPONIVEIS`	503	Tabelas oficiais da NFS-e Nacional (municípios, lista de serviços, NBS, indicadores de operação) indisponíveis no momento, no envio do lote ou na substituição; nada foi gravado	Repita o mesmo lote ou pedido, com os mesmos `idOperacao`, depois dos segundos do cabeçalho `Retry-After`; é seguro repetir. Se persistir, peça suporte. A LideraNota executa este passo: pedir pelo WhatsApp

As recusas de nota no envio do lote não são erros HTTP: vêm na resposta 202, em notas[].erros (aceita: false), com campo e mensagem. Corrija o campo e reenvie com o mesmo idOperacao.

Códigos de transporte

Código	HTTP	Quando	Ação recomendada
`JSON_INVALIDO`	400	Corpo vazio ou JSON malformado	Confira o JSON gerado e o cabeçalho `Content-Type: application/json`
`CORPO_ACIMA_DO_LIMITE`	413	Corpo acima de 5 MB	Divida o envio em lotes menores
`CONTEUDO_NAO_SUPORTADO`	415	`Content-Type` que a API não aceita num `POST`, por exemplo `application/x-www-form-urlencoded`, o padrão do `curl` sem o cabeçalho	Envie o corpo com `Content-Type: application/json`
`REQUISICAO_INVALIDA`	4xx	Demais recusas do protocolo HTTP, por exemplo `Content-Length` que não confere com o corpo	Confira método, endereço, cabeçalhos e corpo
`LIMITE_REQUISICOES_EXCEDIDO`	429	Limite de requisições do token excedido (abaixo); a requisição recusada não é processada	Aguarde os segundos do cabeçalho `Retry-After` e repita; é seguro repetir. Se acontecer com frequência, reduza o ritmo das chamadas
`ROTA_NAO_ENCONTRADA`	404	Método ou caminho inexistente	Confira o método e o caminho; todas as rotas ficam sob `/v1`
`ERRO_INTERNO`	500	Falha inesperada na API	Tente de novo mais tarde. Se persistir, guarde o identificador da requisição que vem na `mensagem` e peça suporte. A LideraNota executa este passo: pedir pelo WhatsApp

Resposta sem o formato de erro acima (por exemplo 502, 503 ou 504 durante uma atualização da API) e falha de rede, tempo esgotado ou erro de TLS: trate como falha temporária e repita mais tarde. O reenvio do mesmo lote é seguro, pela idempotência do idOperacao.

Rejeições da nota

Não são erros HTTP: aparecem em nota.erro.codigo de uma nota rejeitada, na consulta e no webhook, com nota.erro.mensagem em português.

Origem	Códigos	Ação recomendada
Sefin Nacional	Códigos da Sefin Nacional repassados sem mudança, por exemplo `E0240` (CEP do tomador inexistente ou de outro município), `E0315` ou `E0710`. A mensagem dos códigos mais comuns vem traduzida; quando a Sefin Nacional informou uma descrição diferente, a mensagem termina com a descrição original	Consulte o código no leiaute nacional da NFS-e, corrija os dados e envie como operação nova, com `idOperacao` novo
Validação antes do envio	`XSD_INVALIDO` (nota recusada na validação do leiaute) e `DADOS_DPS_INVALIDOS` (dados da nota recusados na montagem da DPS); a mensagem cita o problema	Corrija os dados conforme a mensagem e envie como operação nova, com `idOperacao` novo
Sefin Nacional sem código	`REJEICAO_SEM_CODIGO`: a Sefin Nacional recusou sem informar código	Confira os dados e envie como operação nova; se não houver o que corrigir, peça suporte. A LideraNota executa este passo: pedir pelo WhatsApp

Em qualquer rejeição, emitir de novo exige um idOperacao novo. O CEP do tomador não é conferido na recepção: confira-o no seu sistema antes de enviar, para evitar a rejeição E0240.

Limites de requisições

Grupo	Rotas	Limite vigente
Geral	Envio de lote, consultas do lote e da nota, busca por `idOperacao`, cancelamento, substituição e análise fiscal, somados	60 requisições por minuto por token
Downloads	Download do XML e do DANFSe, somados	600 requisições por minuto por token

Por token: o limite de um token não afeta os demais.
Janela fixa de 1 minuto: acima do limite, a API responde 429 LIMITE_REQUISICOES_EXCEDIDO com o cabeçalho Retry-After, em segundos. Aguarde esse prazo antes de repetir.
Acompanhamento do ritmo: as respostas das rotas sob /v1 trazem x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset (segundos até a janela liberar).
Tamanho do envio: até 500 notas e 5 MB por envio de lote.