Erros

Todo erro HTTP tem o mesmo formato: {erro: {tipo, codigo, mensagem, campo, request_id}}. O tipo define o status HTTP; o codigo diz exatamente o que houve; campo aponta o campo, quando há um.

400requisicao_invalidaRequisição malformada (JSON inválido, header errado)

401autenticacaoChave ausente, inválida ou revogada

403permissaoChave sem o escopo da operação ou conta suspensa

404nao_encontradoRecurso não encontrado (ou de outra conta ou do outro modo, test/live)

409conflitoEstado não permite a operação (nota não cancelável, pedido em andamento…)

422validacaoDados inválidos, regra fiscal ou empresa não pronta para emitir

429limiteMuitas requisições: espere e tente de novo

500internoErro interno: guarde o request_id e fale com o suporte

503indisponivelServiço temporariamente indisponível: tente de novo em instantes

Guarde o request_id: GET /requisicoes/{request_id} mostra o que aconteceu naquela chamada (rota, status, duração, erro e corpo).

Rejeição da SEFIN ou da prefeitura não é erro HTTP: a nota fica rejeitada, com erros: [{codigo, original, mensagem, sugestao}].

Códigos

chave_ausenteautenticacaoO header Authorization não veio.

chave_invalidaautenticacaoChave de API inválida ou revogada.

escopo_insuficientepermissaoA chave não tem o escopo da operação.

conta_suspensapermissaoA conta está suspensa.

empresa_nao_encontradavalidacaoempresa_id não existe nesta conta.

tomador_nao_encontradovalidacaotomador_id não está no catálogo.

servico_nao_encontradovalidacaoservico_id não está no catálogo.

servico_de_outra_empresavalidacaoO serviço do catálogo é de outra empresa.

empresa_nao_prontavalidacaoFalta algo para emitir (veja GET /v1/empresas/{id}/prontidao).

servico_incompletovalidacaoFaltam servico.c_trib_nac e servico.discriminacao (ou servico_id, ou os padrões da configuração fiscal).

valor_obrigatoriovalidacaoFaltou servico.valor.

retencoes_invalidasvalidacaoAs retenções somam mais que o valor do serviço.

c_trib_mun_obrigatoriovalidacaoO município exige o código de tributação municipal (servico.c_trib_mun).

competencia_futuravalidacaoA data de competência não pode ser futura.

tomador_estrangeiro_indisponivelvalidacaoO sistema desta prefeitura ainda não emite nota para tomador estrangeiro (EX); no Emissor Nacional, sim.

exportacao_obrigatoriavalidacaoTomador estrangeiro (EX) no Emissor Nacional exige servico.exportacao: sem ela a SEFIN recusa com E0330.

campo_indisponivel_municipalvalidacaoDescontos, dedução ou informações complementares ainda não saem pelo sistema desta prefeitura; no Emissor Nacional, sim.

base_calculo_invalidavalidacaoDesconto incondicionado e dedução somam o valor do serviço ou mais: a base de cálculo ficaria zerada.

descontos_invalidosvalidacaoDescontos e retenções somam o valor do serviço ou mais.

motivo_invalidovalidacaoO sistema da prefeitura não tem o motivo outros.

sem_emailvalidacaoO tomador não tem e-mail: informe emails_adicionais.

certificado_recusadovalidacaoO .pfx não abriu, é de outro CNPJ ou está vencido.

sem_configuracao_fiscalvalidacaoConfigure a empresa antes de liberar a produção.

cnpj_nao_conferevalidacaoO CNPJ digitado para liberar a produção não é o da empresa.

empresa_nao_configuradavalidacaoConfigure a empresa (e o certificado) antes de testar a conexão.

logo_invalidovalidacaoO logotipo precisa ser PNG ou JPG.

logo_grandevalidacaoO logotipo pode ter até 500 KB.

csv_invalidovalidacaoO CSV precisa de cabeçalho com as colunas documento e nome.

arquivo_grandevalidacaoO CSV pode ter até 5 MB.

empresa_simuladavalidacaoEmpresa simulada não emite em produção.

idempotency_key_invalidavalidacaoIdempotency-Key tem até 255 caracteres.

idempotency_key_reutilizadavalidacaoA Idempotency-Key já foi usada com outro pedido.

dados_invalidosvalidacaoCampo com formato ou valor inválido (veja campo).

nota_nao_cancelavelconflitoSó dá para cancelar nota autorizada.

nota_nao_autorizadaconflitoSó nota autorizada é enviada ao tomador.

nada_a_reprocessarconflitoA nota não está parada nem com falha.

pdf_em_geracaoconflitoO PDF ainda está sendo gerado: tente em instantes.

id_externo_ambiguoconflitoO id_externo existe em mais de uma empresa: informe empresa_id.

pedido_em_andamentoconflitoUm pedido com a mesma Idempotency-Key ainda está em andamento.

lote_em_conflitoconflitoOutro pedido criou notas com os mesmos id_externo agora: repita o lote.

cnpj_ja_cadastradoconflitoEste CNPJ já está cadastrado.

referencia_externa_em_usoconflitoJá existe uma empresa com esta referencia_externa.

tomador_ja_cadastradoconflitoJá existe um tomador com este documento.

nfse_nao_encontradanao_encontradoNota não encontrada (ou do outro modo, test/live).

municipio_nao_encontradonao_encontradoUse o código IBGE de 7 dígitos.

certificado_ausentenao_encontradoA empresa ainda não tem certificado.

sem_certificadonao_encontradoNão há certificado guardado para remover.

pdf_indisponivelnao_encontradoNo caminho municipal o PDF oficial fica no portal da prefeitura.

xml_indisponivelnao_encontradoA nota ainda não tem esse XML.

fila_indisponivelindisponivelA fila de emissão não respondeu: tente de novo.

{
  "erro": {
    "tipo": "validacao",
    "codigo": "empresa_nao_pronta",
    "mensagem": "Antes de emitir: envie o certificado digital A1 (POST /v1/empresas/{id}/certificado).",
    "campo": null,
    "request_id": "req_8f1c2b9e4d1a4a8e9c1f2b7d"
  }
}