---
title: "Como simular erro de processamento na NFS-e"
description: "Como forçar um erro de processamento ao emitir NFS-e no ambiente Development, para testar retries e tratamento de erro na sua integração."
source_url: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/como-simular-erro-de-processamento-nfse-ambiente-de-testes/
product: documentacao
last_updated: 2026-10-03
tags: ["recipe", "nfse", "testes", "erro"]
---

# Como simular erro de processamento na NFS-e

Antes de ir para produção, teste como sua integração reage a uma NFS-e rejeitada. O ambiente **Development** (ambiente de testes/sandbox da API de NFS-e) permite forçar esse cenário de forma controlada, sem depender de uma instabilidade real de prefeitura.

## Pré-requisitos

- Inscrição Municipal da empresa com `Environment: "Development"`.
- Número da Inscrição Municipal diferente dos números de teste reservados (por exemplo `355030999`, `111111`, `222222`). Essas IMs reservadas são enviadas ao ambiente de testes da própria prefeitura e não passam por este comportamento.
- Permissão para emitir NFS-e via API nesse ambiente.

## Solução

No ambiente `Development`, quando o número da Inscrição Municipal não é um dos reservados, a nota é processada por um proxy genérico de testes. Esse proxy sempre aprova a nota — a menos que a descrição do serviço contenha o texto `random error`.

Com esse texto presente, o envio e a consulta do lote têm, cada um, cerca de 1 chance em 3 de falhar. O restante das chamadas é aprovado normalmente.

### Etapa 1: Inclua "random error" na descrição do serviço

Ao montar o payload de emissão, adicione o texto `random error` (não diferencia maiúsculas/minúsculas) em algum ponto do campo de descrição do serviço.

```json
{
  "description": "Consultoria em TI - random error",
  "servicesAmount": 100.00
}
```

### Etapa 2: Envie a nota normalmente

Envie a requisição de emissão como faria em qualquer outro teste, com a IM em `Development`.

```bash
curl -X POST "https://api.nfe.io/v1/companies/{companyId}/serviceinvoices" \
  -H "Authorization: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "cityServiceCode": "0107",
    "description": "Consultoria em TI - random error",
    "servicesAmount": 100.00
  }'
```

### Etapa 3: Consulte o resultado

Consulte o status da nota (ou aguarde o webhook de atualização). Existe uma chance de a resposta indicar falha de processamento, com um destes códigos:

| Momento da falha | Código | Mensagem |
|---|---|---|
| Envio do lote (emissão) | `E998` | Random error on SendBatch. |
| Consulta do lote (checagem de status) | `E999` | Random error on CheckBatch. |

Se a nota não cair no cenário de erro, ela é aprovada normalmente, com número e protocolo simulados.

## Variações

- **Repita o teste várias vezes.** Como o erro não ocorre em toda chamada, rode a emissão algumas vezes até observar a falha, se seu objetivo é validar o tratamento de erro.
- **Combine com outros cenários de teste.** Use `random error` junto com os demais campos que você já testa (retenções, tomador estrangeiro, cliente não identificado) para verificar que o tratamento de erro não interfere no restante da regra de negócio.
- **Teste apenas o caminho de sucesso.** Basta omitir `random error` da descrição — o proxy de testes sempre aprova a nota nesse caso.

## Armadilhas comuns

- **IM de teste reservada.** Se o número da Inscrição Municipal é um dos reservados, a nota vai ao ambiente de testes da prefeitura e `random error` não tem efeito.
- **Tomador com CPF ou CNPJ inválido.** O documento do tomador é validado antes do envio: um valor como `00000000000` devolve `400` na hora e a nota nunca chega ao proxy de testes. Se precisar informar o tomador, use um CPF ou CNPJ válido — o tomador é opcional.
- **Esperar erro determinístico.** O erro é probabilístico, não ocorre em 100% das chamadas. Não trate a ausência de erro na primeira tentativa como falha do teste.
- **Usar em produção.** Esse comportamento existe apenas no ambiente `Development`. Descrições com `random error` em produção são processadas normalmente pela prefeitura real, sem qualquer efeito especial.

## Veja também

- [Tipos de retorno de status das requisições HTTPS](/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/tipos-de-retorno-de-status-das-requisicoes-https)
- [Solução de erros 400 na emissão de NFS-e](/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/solucao-de-erros-400-na-emissao)
- [Primeiros passos para integração de NFS-e](/documentacao/nota-fiscal-servico-eletronica/primeiros-passos)