# Erros e Rejeição

Ao integrar com a API DFe, você vai deparar com dois tipos de retorno bem diferentes. Saber distinguir os dois é o primeiro passo para corrigir o problema com rapidez:

- **Erro da API** — a requisição foi recusada pela própria API (validação, autenticação, conflito de dados). **Nada foi enviado à Sefaz.**
- **Rejeição da Sefaz** — a requisição foi aceita e encaminhada, mas a Sefaz **rejeitou** a nota ou o evento.

> **Importante:** essa distinção também vale para a cobrança. Requisições que chegam à Sefaz são cobradas (mesmo quando rejeitadas); erros da API não são cobrados. Veja o [Modelo de cobrança](#/api/api-dfe/introducao).

## Como identificar um erro da API

Os erros da API chegam com `statusCode` 4xx (erros do cliente) ou 5xx (erros do servidor) e um corpo simples, no formato:

```json
{
  "statusCode": 400,
  "message": ["E-mail ou senha incorretos."],
  "error": "BAD_REQUEST"
}
```

| statusCode | error | O que significa | O que fazer |
|---|---|---|---|
| 400 | BAD_REQUEST | Dados inválidos ou ausentes no payload | Revise os campos enviados (nome, tipo, obrigatoriedade) |
| 401 | UNAUTHORIZED | Token ausente, expirado ou credenciais inválidas | Gere um novo token na rota de login |
| 403 | FORBIDDEN | Requisição não autorizada para aquele token/usuário | Confira se está usando o token correto (usuário × sistema) |
| 409 | CONFLICT | Conflito com dados já cadastrados (ex.: IdExternal duplicado) | Ajuste os dados duplicados e tente novamente |
| 429 | TOO_MANY_REQUESTS | Estourou o limite de requisições por segundo ou minito. Acesse [aqui](#/api/comecando/rate-limit) para conferir os limites. | Aguarde alguns instantes e tente novamente |

> **Dica:** a mensagem detalhada vem sempre no array `message`. Exemplos reais: `"E-mail ou senha incorretos."`, `"Usuário com este IdExternal já está cadastrado."`, `"Acesso negado"`.

Nesses casos a nota **não existe** para a Sefaz: corrija a requisição e envie de novo.

### Erros de servidor (5xx)

Quando o problema é na API ou na infraestrutura por trás dela, a resposta chega com `statusCode` 5xx:

| statusCode | O que significa | O que fazer |
|---|---|---|
| 500 | Erro interno da API | Registre o retorno e tente novamente em instantes |
| 502/503 | Serviço temporariamente indisponível | Confira a [página de status](https://status.dadosjah.com.br/status/dadosjah) e tente mais tarde |
| 504 | Tempo limite de processamento | Refaça a requisição; em emissões síncronas, aumente o timeout do cliente |

> **Nota:** erros 5xx indicam falha do nosso lado ou indisponibilidade temporária — a requisição não foi processada e **não é cobrada**. Se o erro persistir, fale com o suporte.

## Como identificar uma rejeição da Sefaz

Nas rejeições, a resposta HTTP é `200`/`201` (a requisição em si deu certo), mas dentro de `data` a nota volta com `cStat` diferente de sucesso e **sem protocolo**:

```json
{
  "statusCode": 201,
  "data": {
    "NFe": [
      {
        "idDfe": "ef6d2823-005b-4f49-b546-d14aaa0bdb84",
        "nNF": "1820",
        "serie": "1",
        "chDfe": "",
        "cStat": "204",
        "xMotivo": "Rejeição: Duplicidade de NF-e",
        "nProt": ""
      }
    ]
  }
}
```

Os campos que você precisa ler são:

- `cStat` — código numérico do resultado (ex.: `204` = Duplicidade de NF-e);
- `xMotivo` — descrição textual. **É aqui que está a causa da rejeição;**
- `nProt` — protocolo de autorização. Vazio em caso de rejeição.

O mesmo padrão vale para consultas (`GET`), eventos, cancelamentos e inutilizações. Em **eventos**, o protocolo aparece como `nProtEvt` (ou `nProtCan`, `nProtInu`).

## Passo a passo para corrigir uma rejeição

1. **Leia o `xMotivo`** — ele diz exatamente qual campo ou regra foi violada;
2. **Identifique o campo citado** no seu payload de emissão;
3. **Corrija o dado** (tabela de códigos, código IBGE, data, IE, CRT, etc.);
4. **Reenvie a nota** com o mesmo número e série. Como a nota rejeitada **não foi autorizada**, a numeração não é "consumida" — exceto em rejeições de duplicidade (204/539), que indicam que a nota **já existe** na Sefaz. Nesse caso, verifique primeiro o que já foi emitido;
5. **Em lotes:** cada nota é enviada individualmente à Sefaz. Se uma for rejeitada, as demais do lote seguem normalmente;
6. **Emissão assíncrona:** os mesmos campos `cStat`/`xMotivo` aparecem na consulta do resultado (por `idBatch`, chave ou número) — veja [Conceitos](#/api/api-dfe/conceitos).

> **Atenção:** rejeição é cobrada, pois a requisição chegou à Sefaz. Homologue o fluxo em `tpAmb: 2` antes de ir para produção.

## Rejeições mais comuns

| cStat | xMotivo | Causa provável | Como corrigir |
|---|---|---|---|
| 203 | Emissor não habilitado para emissão da NF-e | CNPJ sem credenciamento junto à Sefaz ou sem autorização para aquele ambiente | Verifique o credenciamento do emitente e use o `tpAmb` correto |
| 204 | Duplicidade de NF-e | Já existe nota autorizada com a mesma chave | Confirme se a nota já foi emitida antes de reenviar |
| 539 | Duplicidade de NF-e, com diferença na Chave de Acesso | Mesmo número/série já utilizado com outros dados | Verifique a numeração usada e corrija os campos divergentes |
| 573 | Duplicidade de Evento | Evento (cancelamento, CC-e...) já registrado para a nota | Não é possível registrar o mesmo evento duas vezes; consulte o evento existente |

> **Dica:** os códigos de rejeição são padronizados nacionalmente. A lista completa e atualizada está no Manual de Orientação do Contribuinte, no [Portal da NF-e](https://www.nfe.fazenda.gov.br/), assim como nas notas técnicas. Para NFSe é necessário acessar o [portal da nfse do padrão nacional](https://www.gov.br/nfse/pt-br) ou o portal do provedor, pode solicitar ao suporte da prefeitura também. 

### Denegação de uso (110) e Denegada (301/302)

Diferente da rejeição — em que a nota é recusada e você corrige e reenvia —, a **denegação** indica que a nota foi recebida pela Sefaz, mas **não tem validade fiscal** por irregularidade cadastral:

Os códigos 110, 301 e 302 indicam que há irregularidade fiscal no emitente ou destinatário. Solicite ao emitente e/ou destinatário para verificarem a situação junto a Sefaz do seu estado.

> **Atenção:** nota denegada **não vale como documento fiscal**. Nesse caso, **não** corrija a nota e reenvie — a pendência é cadastral, não do payload. Regularize a situação na Sefaz (emitente ou destinatário) e só então emita novamente.

### Rejeições em eventos (cancelamento, inutilização, CC-e)

Além do `cStat`/`xMotivo`, fique atento a duas regras que costumam gerar rejeição:

- **Justificativas** (`xJust` para cancelamento/inutilização, `xCorrecao` para CC-e): obrigatórias, com no mínimo **15 caracteres**;
- **Sequencial de evento** (`nSeqEvento`): deve ser incrementado a cada evento novo da mesma nota (1ª CC-e = `1`, 2ª = `2`...).

## Erros específicos da NFS-e

Na NFS-e, além de `cStat`/`xMotivo`, a resposta pode trazer um array `errors` com a orientação de correção já detalhada pelo provedor:

```json
{
  "situation": "Error",
  "errors": [
    {
      "codigo": "S10",
      "correcao": "Informe a inscrição municipal do prestador.",
      "descricao": "Inscrição Municipal inválida ou não informada."
    }
  ]
}
```

- `codigo` — código técnico do erro no provedor;
- `descricao` — detalhamento técnico;
- `correcao` — orientação direta do que corrigir.

> **Nota:** na NFS-e a rejeição depende do provedor/prefeitura. Alguns pedem apenas usuário e senha; cada município tem regras próprias de validação.

## Erro de validação do schema XML

Antes de ir à Sefaz, a nota passa por uma validação do **leiaute oficial** (schema XML). Se o XML gerado a partir do seu payload não estiver em conformidade com o schema, a API retorna erro de validação com o código `X800` (Erro de Validação de Schema XML):

```json
{
  "statusCode": 201,
  "data": {
    "events": [
      {
        "situation": "Error",
        "errors": [
          {
            "codigo": "X800",
            "correcao": "",
            "descricao": "Erro de Validação: ..."
          }
        ]
      }
    ]
  }
}
```

- `descricao` — aponta qual campo ou estrutura violou o schema (tipo, tamanho, obrigatoriedade);
- **Causas comuns:** campo obrigatório ausente, tipo ou quantidade de caracteres errada (ex.: IE, CST, códigos IBGE), estrutura do payload fora do leiaute;
- **Como corrigir:** compare o payload com o exemplo de requisição da [collection do Postman](https://documenter.getpostman.com/view/53424652/2sBXikoBN8) e valide os campos críticos listados em [Conceitos](#/api/api-dfe/conceitos).

> **Importante:** falhas de validação de schema (assim como erros internos da API) **não são cobradas**, pois a nota não chegou à Sefaz.

## Quando reenviar e quando não reenviar

| Situação | Devo reenviar? | O que fazer |
|---|---|---|
| Erro de validação da API (4xx) | ✅ Sim | Corrija o payload e reenvie — a nota não chegou à Sefaz |
| Rejeição da Sefaz (`cStat` ≠ 100/120/150) | ✅ Sim | Corrija conforme o `xMotivo` e reenvie com o mesmo número e série |
| Duplicidade (204/539) | ❌ Não | A nota **já existe** na Sefaz — consulte o que foi emitido antes de reenviar |
| Denegação (110/301/302) | ❌ Não | Regularize a pendência cadastral na Sefaz |
| Erro transitório (5xx, 429, timeout, Sefaz fora) | ✅ Sim, com cuidado | Aguarde e repita a mesma requisição dentro de alguns instantes, sem alterar o payload |

### Sem idempotência: reenvio não é "replay"

A API **não possui idempotência**: cada documento enviado é tratado como uma emissão nova, e quem distingue a duplicidade é a Sefaz. Por isso:

- O campo `IdExternal` **não é uma chave única** — pode se repetir ou ser omitido entre documentos sem impedir a emissão;
- Reenviar o mesmo payload depois de um timeout ou falha de comunicação pode gerar **duplicidade** (204/539), caso a primeira tentativa já tenha sido autorizada;
- **Antes de reenviar** nesses casos, consulte a nota (por chave, série/número ou lote) para confirmar se ela já foi autorizada.

## Evitando erros antes de enviar

Muita rejeição pode ser evitada antes mesmo da emissão:

- **Comece em homologação** (`tpAmb: 2`) e só passe a emitir em produção quando o fluxo estiver validado;
- **Valide os campos críticos** — `tpAmb`, datas com fuso, IE/IM, CRT, códigos IBGE. Consulte a lista completa em [Conceitos](#/api/api-dfe/conceitos);
- **Use as listas fiscais da própria API** (`/v1/lists/*`) para conferir NCM, CFOP, CEST e CSTs antes de montar o payload;
- **Na emissão síncrona**, ajuste o timeout da sua aplicação para cerca de 60 segundos — timeouts do cliente não significam rejeição fiscal;
- **Confira o status da Sefaz** com `/v1/nfe/service-status?UF=...&tpAmb=...` quando houver falhas de comunicação ou lentidão.

## Logs de comunicação e suporte

A comunicação completa com a Sefaz (envelopes SOAP, retornos, tentativas) é registrada em **logs internos da aplicação** — não há endpoint de debug que exponha esses arquivos para o integrador.

Se uma rejeição persistir mesmo seguindo o `xMotivo` e as orientações desta página, fale com o suporte e envie:

- O **retorno completo** da API (`cStat`, `xMotivo`, `nProt`) e o **payload** enviado;
- A **data e hora** aproximadas da requisição.

Com esses dados, a equipe de suporte consulta os logs internos e identifica o que aconteceu na comunicação com a Sefaz.

## Resumo: o que fazer diante de cada retorno

| O que você recebeu | Significado | Próximo passo |
|---|---|---|
| `statusCode` 4xx/5xx | Erro da API — não chegou à Sefaz | Corrija payload/credenciais e reenvie (não cobrado) |
| `200`/`201` com `cStat = [100, 120, 150]` e `nProt` preenchido | Nota autorizada | Sucesso — guarde o `nProt` |
| `200`/`201` com `cStat ≠ [100, 120, 150]` e `nProt` vazio | Rejeição da Sefaz | Corrija conforme o `xMotivo` e reenvie (cobrado) |
| `200`/`201` com `cStat = [110, 301, 302]` | Nota denegada — irregularidade cadastral | Não reenvie: regularize a pendência na Sefaz e depois emita/consulte novamente |
| `situation: "Error"` com `errors[].codigo` (ex.: `X800`) | Falha de validação do schema XML — não chegou à Sefaz | Corrija o payload conforme a `descricao` e reenvie (não cobrado) |
| Timeout ou falha de comunicação | Indisponibilidade da Sefaz ou da API | Consulte o status do webservice da Sefaz |

> **Importante:** a referência completa, com todos os endpoints, parâmetros e exemplos de resposta, está na documentação do Postman da [API DFe](https://documenter.getpostman.com/view/53424652/2sBXikoBN8). Se a rejeição persistir, fale com o suporte.
