# Erros

Todo erro tem o mesmo formato (`codigo`, `mensagem` e, na validação, `erros`; veja [Formato dos erros](02-autenticacao.md#formato-dos-erros)). **Programe contra o `codigo`**, que é estável; a `mensagem` é para uma pessoa ler e pode mudar de redação.

## Catálogo de códigos

| HTTP | `codigo` | Significa | O que fazer |
|---|---|---|---|
| `401` | `nao_autorizado` | chave ausente, inválida, revogada ou vencida (a mesma resposta nos quatro casos) | confira a chave; peça uma nova se foi revogada ou venceu. **Não** repita em laço |
| `403` | `conta_inativa` | a conta foi desativada | fale com o suporte |
| `404` | `empresa_nao_encontrada` | o CNPJ não existe **ou** não é da sua conta (a mesma resposta) | confira o CNPJ e a chave |
| `404` | `nota_nao_encontrada` | não há nota com essa `ref` nessa empresa e nesse ambiente | confira `ref`, `cnpj_emitente` e o ambiente atual da empresa |
| `404` | `produto_nao_encontrado` | não há produto com esse SKU nessa empresa | confira o SKU |
| `404` | `webhook_nao_encontrado` · `entrega_nao_encontrada` | o webhook ou a entrega não existe nesta conta | confira o `id` |
| `404` | `nao_encontrado` | rota ou arquivo que não existe (ou XML/DANFE ainda não disponível) | confira a URL; o XML só existe depois da autorização |
| `405` | `metodo_nao_permitido` | o método HTTP não vale para esta rota | confira o método na [referência](12-referencia.md) |
| `409` | `ref_ja_utilizada` | a `ref` já pertence a uma nota com **outro** conteúdo | se é a mesma venda, reenvie o conteúdo original; se é uma venda nova, use uma `ref` nova. `status_atual` diz em que estado está a nota |
| `422` | `requisicao_invalida` | formato, campo desconhecido, dado faltando, valor que não fecha. **Todos** os problemas vêm em `erros`, por campo | corrija os campos apontados e reenvie. Repetir igual não adianta |
| `422` | `validacao_fiscal` | o cálculo ou a empresa não permitem emitir: total que não fecha, cenário tributário não suportado, certificado vencido, empresa inativa, produção bloqueada | leia a `mensagem` (diz o que ajustar); corrija o cadastro ou os parâmetros fiscais |
| `422` | `cnpj_emitente_obrigatorio` | a conta tem mais de uma empresa e você não disse qual | envie `cnpj_emitente` |
| `422` | `limite_de_empresas` | a conta já tem o máximo de empresas | fale com o suporte para ampliar |
| `422` | `limite_de_webhooks` | a conta já tem o máximo de endereços de webhook (10) | remova um que não usa mais |
| `422` | `numero_retroativo` | o próximo número informado para a série é menor ou igual ao maior já usado nela (a numeração não volta) | use ao menos o `minimo` da resposta; número já usado não se reaproveita |
| `429` | `limite_de_requisicoes` | estourou o limite por minuto | espere o `Retry-After` (segundos) e repita |
| `5xx` | `erro_interno` | falha da plataforma | tente de novo depois de alguns segundos (com a **mesma `ref`**, repetir é seguro). Se persistir, cite o `X-Request-Id` ao suporte |

### Quando repetir a chamada

| Resposta | Repetir? |
|---|---|
| falha de rede, tempo esgotado, `5xx`, `429` | **sim**, com espera crescente. No `POST /nfe`, com a **mesma `ref` e o mesmo corpo** (é idempotente) |
| `401`, `403`, `404`, `405` | não: o problema é de chave, permissão ou endereço |
| `409`, `422` | não, **sem mudar nada**: corrija o que foi apontado |

## Como ler um `422`

`erros` é um objeto com **o caminho de cada campo** com problema e a lista de mensagens dele:

```json
{
  "codigo": "requisicao_invalida",
  "mensagem": "O campo nome destinatario é obrigatório.",
  "erros": {
    "nome_destinatario": ["O campo nome destinatario é obrigatório."],
    "items.0.codigo_ncm": ["O campo items.0.codigo_ncm deve ter 8 dígitos."],
    "formas_pagamento.1.valor_pagamento": ["..."]
  }
}
```

- `items.0.codigo_ncm` é o campo `codigo_ncm` do **primeiro** item (a contagem começa em 0).
- Erros de **importação** de produtos citam a linha: `"Linha 2: O campo NCM deve ter 8 dígitos."` (a linha é a posição na lista, começando em 1).
- Alguns erros não são de um campo, mas de uma regra: `erros.faixa` na inutilização, `erros.nota` num cancelamento fora do prazo, `erros.ambiente` com o que impede a produção, `erros.certificado` para um certificado recusado.
- `mensagem` repete o **primeiro** erro, para registrar numa linha de log.

## Recusa fiscal (`validacao_fiscal`)

Não é um defeito do JSON: o JSON está certo, mas o **cálculo** ou a **empresa** não permitem emitir. As mensagens dizem o que ajustar. As mais comuns:

| Mensagem (resumo) | O que fazer |
|---|---|
| `Total calculado (X) difere do total informado (Y).` | os valores estão em **centavos**. Confira preços, quantidades, frete, desconto e IPI; ou omita `valor_total` |
| `A soma das formas de pagamento (X) difere do valor da nota (Y).` | acerte os `valor_pagamento` |
| `Com mais de uma forma de pagamento, informe o valor de cada uma.` | informe `valor_pagamento` em todas |
| `Certificado A1 ... ausente ou vencido.` | envie um certificado válido ([Empresas](03-empresas.md#certificado-digital-a1)) |
| `Emissão em produção bloqueada: as tabelas fiscais ... (FISCAL_RATES_VERIFIED).` | a plataforma ainda não liberou a produção; emita em homologação ou fale com o suporte |
| `CSOSN 900 ... não é suportado` (e similares) | o cenário tributário (ICMS-ST como substituto, por exemplo) ainda não é coberto: veja [Modo híbrido](07-modo-hibrido.md) |
| `NCM inválido no item ...` | o NCM tem de ter 8 dígitos |
| `Vendedor industrial: cadastre ipi_cst/ipi_aliq ...` | empresa industrial exige a situação tributária e a alíquota do IPI no item |
| `UF inválida ou sem tabela fiscal` | confira a UF do destinatário |

## Rejeições comuns da SEFAZ

Se a nota passa pela validação e a SEFAZ a rejeita, o `status` fica `erro_autorizacao` e a nota traz `status_sefaz` (o `cStat`) e `mensagem_sefaz` (o texto original). **Ao conferir, o texto da SEFAZ é o que vale.** Os códigos abaixo são a leitura habitual da tabela da SEFAZ:

| `status_sefaz` | Costuma indicar | O que fazer |
|---|---|---|
| `203` | emissor não habilitado para emitir NF-e na UF | o CNPJ/IE precisa estar **credenciado** para emitir NF-e na SEFAZ da UF (vale também em homologação em várias UFs) |
| `209`, `233`, `234` | inscrição estadual do emitente inválida, não cadastrada ou não vinculada ao CNPJ | confira a `ie` da empresa ([`PATCH /empresas/{cnpj}`](03-empresas.md#atualizar-uma-empresa)) |
| `213` | o CNPJ do certificado não é o da empresa | envie o certificado correto |
| `280` a `286` | problema no certificado: inválido, vencido, sem CNPJ, cadeia não ICP-Brasil | envie um **e-CNPJ A1 ICP-Brasil** válido |
| `225` | falha de schema XML | é defeito do lado da plataforma: abra um chamado com o `ref` e o `X-Request-Id` |
| `108`, `109` | serviço da SEFAZ paralisado | **nada a fazer**: a plataforma tenta de novo sozinha por até 6 horas; a nota fica `processando_autorizacao` |
| `204`, `539` | a SEFAZ já tem uma nota com esta chave | tratado pela plataforma: ela consulta a chave e dá a nota por autorizada, sem emitir outra |
| `110`, `301`, `302`, `303` | uso denegado | o `status` fica `denegado`: o número foi consumido e a nota não vale. Fale com o contador; para vender de novo, use uma `ref` nova |

Em caso de rejeição, **corrija e reenvie na mesma `ref`**: o número fiscal é o mesmo (rejeição não consome número) e o histórico fica coerente.

## Problemas frequentes

**A nota está em `processando_autorizacao` há muito tempo.** A SEFAZ pode estar lenta ou fora do ar. A plataforma tenta de novo sozinha por até 6 horas e, depois de uma falha de comunicação, **consulta a chave antes de reenviar** (para nunca emitir duplicado). Consulte `GET /nfe/{ref}`: se `mensagem` trouxer uma falha de comunicação, é a SEFAZ. Não reenvie a mesma venda com `ref` nova: criaria uma segunda nota.

**Recebi `401` e a chave é a mesma de ontem.** A chave foi revogada ou venceu. Peça uma nova (e, na rotação, siga o [passo a passo](10-producao.md#chaves-de-api)).

**O webhook não chega.** (1) Use `POST /webhooks/{id}/teste` e veja o resultado; (2) em `GET /webhooks/{id}/entregas`, confira `ultimo_status_http` e `ultimo_erro`; (3) o endereço precisa ser `https` e público (não `localhost`); (4) o seu servidor precisa responder `2xx` em até 10 segundos; (5) confira se o `ativo` é `true` e se `eventos` inclui o evento esperado.

**`422` com `codigo_municipio_destinatario`.** A API não conseguiu descobrir o município pelo CEP. Informe `codigo_municipio_destinatario` (código IBGE de 7 dígitos).

**A mesma nota foi emitida duas vezes.** Só acontece se você usou **`ref` diferentes** para a mesma venda. Com a mesma `ref`, repetir devolve sempre a mesma nota. Use um identificador estável da venda (o número do pedido) como `ref`.

**Preciso corrigir o valor de uma nota autorizada.** Valores e impostos **não** se corrigem com carta de correção. Dentro do prazo, cancele ([Cancelar](06-eventos.md#cancelar)) e emita outra com `ref` nova; fora dele, é devolução ou estorno com o contador.