Erros - Invo API

Os erros vêm em JSON com o campo error. Há dois formatos. Quando uma regra de negócio recusa a requisição, error traz uma mensagem legível:

{ "error": "Empresa não está apta a emitir NF-e" }

Quando um campo não segue o schema do endpoint, error vale invalid_params. O campo params repete a estrutura da requisição e diz o problema de cada campo:

{
  "error": "invalid_params",
  "params": {
    "destinatario": {
      "endereco": {
        "logradouro": "o comprimento deve ser no mínimo 2"
      }
    }
  }
}

Campo obrigatório ausente, tipo errado e texto fora do tamanho permitido caem nesse formato. O schema de cada endpoint mostra essas regras, nas abas API NF-e e API NFS-e.

Códigos de status

Código	Significado
`200 OK`	Sucesso em consulta, download ou inutilização.
`201 Created`	A nota foi criada e entrou na fila de emissão.
`202 Accepted`	O cancelamento começou e segue de forma assíncrona.
`401 Unauthorized`	Credenciais HTTP Basic ausentes ou inválidas.
`404 Not Found`	A empresa de `X-Empresa-CNPJ` ou a nota não existe.
`406 Not Acceptable`	`Accept` diferente de JSON num endpoint JSON.
`409 Conflict`	O DANFE ainda não está disponível, porque a nota não tem XML autorizado.
`422 Unprocessable Entity`	Erro de validação, empresa inapta ou rejeição da SEFAZ.
`502 Bad Gateway`	Falha de comunicação com a SEFAZ. O resultado é desconhecido.

Mensagens comuns (`422`)

Mensagem	Contexto
`Empresa não está apta a emitir NF-e`	Emissão ou inutilização para uma empresa sem IE, CRT ou certificado ativo.
`Código externo já está em uso`	`codigo_externo` repetido na mesma empresa e no mesmo ambiente. O mesmo código pode existir uma vez em produção e uma vez em sandbox.
`Esta nota de produto já está cancelada`	Pedido de cancelamento para uma nota já cancelada.
`Apenas notas de produto autorizadas podem ser canceladas`	Pedido de cancelamento para uma nota que não está autorizada.
`numero_final deve ser maior ou igual a numero_inicial`	Faixa de inutilização com `numero_final` menor que `numero_inicial`.
`Pagamentos a soma dos pagamentos (R$ 50,00) deve fechar com o total da nota mais o troco (R$ 105,00)`	A soma de `pagamentos` difere do total da nota mais o `troco`.
`Pagamentos cartao tipo integracao é obrigatório para a forma de pagamento 03 (grupo cartão)`	Crédito, débito ou PIX dinâmico sem o grupo `cartao`.
`Troco exige ao menos uma forma de pagamento`	`troco` sem nenhum item em `pagamentos`.
`Indicador de Presença deve ser 1, 2, 3, 4 ou 9 quando há intermediador`	`intermediador` com `indicador_presenca` ausente, nulo, `0` ou `5`.
`CNPJ do Intermediador não é válido`	`intermediador.cnpj` com dígito verificador errado ou com letras.
`Identificador no Intermediador é muito curto (mínimo: 2 caracteres)`	`intermediador.identificador_cadastro` com menos de 2 caracteres. O limite máximo é 60.
`Identificador no Intermediador não pode ter espaço nas pontas, tab, quebra de linha nem caracteres fora do Latin-1`	`intermediador.identificador_cadastro` fora do padrão do XSD. A Invo não altera o valor.

As demais regras de pagamentos estão no guia de pagamentos. As regras de intermediador estão na seção Venda em marketplace.

Uma falha de comunicação com a SEFAZ retorna 502 com a mensagem genérica Falha de comunicação com a SEFAZ. Por segurança, o corpo não traz os detalhes da exceção. Para investigar, consulte a trilha de eventos da nota.