---
title: "Mensagens de erro da API de NFS-e (PT/EN)"
description: "Catálogo de onde cada mensagem de erro da API de NFS-e aparece, com o texto literal em inglês, a tradução de referência em português, a causa e a ação."
source_url: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/duvidas/erros-e-status/mensagens-de-erro-da-api-nfse/
product: documentacao
last_updated: 2026-10-12
tags: ["nfse", "erro", "catalogo", "flowmessage", "http", "referencia"]
---

# Mensagens de erro da API de NFS-e (PT/EN)

Esta página mostra **onde** cada mensagem de erro da API de NFS-e aparece, **qual é o texto literal** e **o que ele significa em português**. Use-a para achar a causa de um erro e a ação que resolve.

A página complementa o [catálogo de erros 400 na emissão](./cenarios-de-badrequest-na-emissao.md). Aquela página detalha cada campo do payload. Esta reúne os outros endpoints, o campo `flowMessage` e a tradução.

## Como usar este catálogo

A API devolve mensagens em **inglês**. Algumas mensagens de prefeituras e de integrações novas já chegam em português, e há mensagens que misturam os dois idiomas. A API ainda não permite escolher o idioma da resposta.

:::warning Tradução de referência
A coluna **Português** é uma tradução de referência desta documentação. A API **não** devolve esse texto. Para casar uma mensagem em automações, use o texto em inglês da coluna **Mensagem (EN)**.
:::

Uma mensagem de erro aparece em três lugares:

| Onde aparece | Formato | Como ler |
|---|---|---|
| Corpo da resposta HTTP 400, 404, 409 ou 422 | Texto simples. Quando várias regras falham, o corpo traz só a primeira mensagem | Veja [Respostas HTTP](#respostas-http) |
| Corpo da resposta HTTP 400 de formato de JSON | `application/problem+json`, com o caminho do campo em `errors` | Veja [Erros de formato do JSON](#erros-de-formato-do-json) |
| Campo `flowMessage` da nota | Texto livre, no `GET` da nota e no payload do webhook | Veja [Campo flowMessage](#campo-flowmessage) |

:::tip Valor entre chaves
Nos textos abaixo, `{campo}`, `{id}` e similares marcam o valor que a API preenche na mensagem. A API nunca devolve as chaves.
:::

## Respostas HTTP

As tabelas desta seção cobrem a resposta síncrona da API, na ordem em que você encontra os erros ao integrar. O status HTTP está na coluna **Onde**.

### Validação do corpo na emissão

Onde: `POST /v1/companies/{companyId}/serviceinvoices`, status **400**. O texto é sempre `{campo} <regra>`, em que `{campo}` é o caminho do campo no JSON (por exemplo `borrower.address.city.code`). A tabela lista cada modelo de mensagem.

| Mensagem (EN) | Português | Campos que disparam |
|---|---|---|
| `{campo} can not be null` | `{campo}` não pode ser nulo | `location.city`, `borrower.address.city`, `foreignTrade.serviceAmountInCurrency`, `foreignTrade.mdicDelivery`, `Body` |
| `{campo} can not be null or empty` | `{campo}` não pode ser nulo nem vazio | `cityServiceCode`, `description`, `location.city.code`, `location.city.name`, `location.state`, `borrower.address.postalCode`, `borrower.address.street`, `borrower.address.state`, `foreignTrade.currency` |
| `{campo} must be a valid IBGE city code` | `{campo}` deve ser um código IBGE de cidade válido | `location.city.code`, `borrower.address.city.code` |
| `{campo} must be a valid ISO 3166-2 code, samples (SP, RJ, AC)` | `{campo}` deve ser uma sigla de UF válida (ISO 3166-2), por exemplo SP, RJ, AC | `location.state`, `borrower.address.state` |
| `{campo} must be a valid ISO 3166-1 code, samples (BRA, ARG, COL)` | `{campo}` deve ser um código de país válido (ISO 3166-1), por exemplo BRA, ARG, COL | `borrower.address.country` |
| `{campo} can not be less than zero` | `{campo}` não pode ser menor que zero | `deductionsAmount`, `discountConditionedAmount`, `discountUnconditionedAmount`, `irAmountWithheld`, `pisAmountWithheld`, `cofinsAmountWithheld`, `csllAmountWithheld`, `inssAmountWithheld`, `issAmountWithheld`, `othersAmountWithheld`, `foreignTrade.serviceAmountInCurrency`, `rpsSerialNumber` |
| `{campo} can not be less than 0.00` | `{campo}` não pode ser menor que 0,00 | `servicesAmount` |
| `{campo} can not be less than or equal zero` | `{campo}` não pode ser menor ou igual a zero | `rpsNumber` |
| `{campo} can not be less than 0.00 (0%)` | `{campo}` não pode ser menor que 0,00 (0%) | `issRate`, `approximateTax.TotalRate` |
| `{campo} can not be more than 0.05 (5%)` | `{campo}` não pode ser maior que 0,05 (5%) | `issRate` |
| `{campo} can not be more than 99.99 (99.99%)` | `{campo}` não pode ser maior que 99,99 (99,99%) | `approximateTax.TotalRate` |
| `{campo} must be exactly 6 digits` | `{campo}` deve ter exatamente 6 dígitos | `ibsCbs.classCode`, `ibsCbs.operationIndicator` |
| `{campo} must contain from 1 to 12 digits` | `{campo}` deve ter de 1 a 12 dígitos | `construction.encapsulationNumber` |
| `{campo} must contain only digits` | `{campo}` deve conter apenas dígitos | `intermediary.address.city.code`, `recipient.address.city.code` |
| `{campo} length must be less than 500 characters` | `{campo}` deve ter menos de 500 caracteres | `additionalInformation` |
| `{campo} length must be less than 115 characters` | `{campo}` deve ter menos de 115 caracteres | `borrower.name` |
| `{campo} can not be less than 7 digits` | `{campo}` não pode ter menos de 7 dígitos | `borrower.phoneNumber` |
| `{campo} can not be longer than 20 digits` | `{campo}` não pode ter mais de 20 dígitos | `borrower.phoneNumber` |
| `{campo} borrower federal tax number is not valid` | O CPF/CNPJ do tomador em `{campo}` não é válido | `borrower.federalTaxNumber` |
| `{campo} is not valid for natural person` | `{campo}` não é válido para pessoa física | `borrower.federalTaxNumber` |
| `{campo} is not valid for legal person` | `{campo}` não é válido para pessoa jurídica | `borrower.federalTaxNumber` |
| `{campo} is invalid` | `{campo}` é inválido (valor fora da lista permitida) | `foreignTrade.serviceMode`, `foreignTrade.relationShip`, `foreignTrade.supportMechanismProvider`, `foreignTrade.supportMechanismReceiver`, `foreignTrade.temporaryGoods` |
| `{campo} is not a valid state code` | `{campo}` não é uma UF válida | `borrower.address.state` |
| `{campo} is not a valid city code or city` | `{campo}` não é um código de cidade ou cidade válido | `borrower.address.city.code` |
| `{campo} aren't related. inform the correct state associated with correct city code` | `{campo}` não se relacionam. Informe a UF correta para o código da cidade | `borrower.address.city.code` e `borrower.address.state` |
| `{campo} from DB differs of city state informed` | A UF cadastrada para a cidade em `{campo}` difere da UF informada | `borrower.address.state` |

Para a regra exata de cada campo e como evitar o erro, use a tabela por campo em [Cenários de erro 400 na emissão](./cenarios-de-badrequest-na-emissao.md).

:::note
Quando vários campos falham, o corpo da resposta traz **só a primeira** mensagem. Corrija, envie de novo e leia a seguinte.
:::

### Regras de negócio e estado da nota

Estas mensagens vêm de regras da plataforma, depois que o corpo passa na validação. O status está na coluna **Onde**.

| Onde | Mensagem (EN) | Português | Causa e ação |
|---|---|---|---|
| `POST` e `DELETE` da nota, **400** | `Municipal tax is not allowed to issue invoice` | A inscrição municipal não está habilitada para emitir nota | A habilitação fiscal da empresa não está ativa. Confira o cadastro da empresa. No cancelamento a frase também diz "issue" |
| Qualquer rota da nota, **400** | `company is not active` | A empresa não está ativa | A empresa está inativa. Reative a empresa e tente de novo |
| Qualquer rota da nota, **404** | `Company not found.` | Empresa não encontrada | O `companyId` não existe na conta. Confira o identificador |
| `POST`, `DELETE` e listagem da nota, **404** | `Municipal tax not found.` | Inscrição municipal não encontrada | A empresa não tem inscrição municipal cadastrada. Cadastre antes de emitir |
| `POST` da nota, **400** | `service invoice with rps number ({rpsNumber}) already exists` | Já existe nota com o número de RPS (`{rpsNumber}`) | O RPS já foi usado. Use o próximo número livre |
| `POST` da nota, **400** | `service invoice with external id ({externalId}) already exists` | Já existe nota com o identificador externo (`{externalId}`) | O `externalId` já foi usado. Consulte a nota existente por `externalId` antes de reenviar |
| `GET`, `DELETE`, `reprocess` da nota, **404** | `service invoice with id ({invoiceId}) was not found` | Nota fiscal com id (`{invoiceId}`) não encontrada | O `id` não existe nessa empresa. Confira o `id` e o `companyId` |
| `PUT .../reprocess`, **400** | `invoice is processing` | A nota está em processamento | Aguarde o fim do processamento antes de reprocessar |
| `PUT .../reprocess`, **400** | `invoice with this status can't be reprocessed` | Uma nota com este status não pode ser reprocessada | Só notas com falha podem ser reprocessadas. Consulte o `status` da nota |
| `GET .../cancellation-xml`, **404** | `Cancellation event XML not available for this service invoice (National environment only; legacy providers have no cancellation event XML, or the invoice has not been cancelled).` | XML do evento de cancelamento indisponível para esta nota (somente ambiente Nacional; provedores legados não têm esse XML, ou a nota não foi cancelada) | Confirme se a nota foi cancelada e se o município usa o ambiente Nacional |

:::warning
RPS ou `externalId` duplicado retorna **400**, não 409. Trate a duplicidade pela mensagem, não por um status fixo.
:::

### Consulta e paginação

Onde: `GET /v1/companies/{companyId}/serviceinvoices` e as consultas por `externalId` ou por RPS, status **400**.

| Mensagem (EN) | Português | Ação |
|---|---|---|
| `page count must be greater then zero` | O tamanho da página deve ser maior que zero | Envie `pageCount` maior que 0 |
| `page index must be greater then zero` | O índice da página deve ser maior que zero | Envie `pageIndex` maior que 0 |
| `page count must be less then equal to 50` | O tamanho da página deve ser menor ou igual a 50 | Envie `pageCount` até 50 |
| `external id is null or empty` | O identificador externo é nulo ou vazio | Informe o `externalId` na rota |
| `issued begin must have a value` | A data inicial de emissão deve ter valor | Informe `issuedBegin` junto com `issuedEnd` |
| `issued end must be greater then issued begin` | A data final de emissão deve ser maior que a inicial | Use `issuedEnd` posterior a `issuedBegin` |
| `created begin must have a value` | A data inicial de criação deve ter valor | Informe `createdBegin` junto com `createdEnd` |
| `created end must be greater then created begin` | A data final de criação deve ser maior que a inicial | Use `createdEnd` posterior a `createdBegin` |
| `borrower federal tax number is not valid` | O CPF/CNPJ do tomador não é válido | Corrija `borrowerFederalTaxNumber` |
| `service invoice RPS number is not valid` | O número de RPS da nota não é válido | Corrija `rpsNumber` |
| `service invoice number is not valid` | O número da nota não é válido | Corrija `number` |
| `The value '{valor}' is not valid.` | O valor '`{valor}`' não é válido | O tipo do parâmetro de rota ou query está errado (`pageIndex`, `status`, `issuedBegin` e similares) |

### Download de arquivos por link assinado

Onde: `GET /v1/blob/download`, o link assinado de PDF e XML.

| Status | Mensagem (EN) | Português | Ação |
|---|---|---|---|
| 400 | `Invalid parameters.` | Parâmetros inválidos | O link está incompleto ou foi alterado. Gere um novo link na nota |
| 404 | `File not found or an error occurred.` | Arquivo não encontrado ou ocorreu um erro | O link expirou ou o arquivo não existe. Gere um novo link |
| 503 | `Storage temporarily unavailable.` | Armazenamento temporariamente indisponível | Tente de novo após o intervalo do cabeçalho `Retry-After` (30 segundos) |
| 500 | `An error occurred while downloading the file.` | Ocorreu um erro ao baixar o arquivo | Tente de novo. Se repetir, abra chamado com o `id` da nota |

### Eventos da autoridade fiscal

Onde: `.../serviceinvoices/{invoiceId}/authority-events`.

| Status | Mensagem (EN) | Português | Ação |
|---|---|---|---|
| 409 | `an authority event of type '{eventType}' is already active for this service invoice` | Já existe um evento do tipo '`{eventType}`' ativo para esta nota | Aguarde a conclusão do evento atual |
| 404 | `authority event '{eventId}' was not found for this service invoice` | O evento '`{eventId}`' não foi encontrado para esta nota | Confira o `id` do evento |
| 404 | `Authority event XML not available yet for this event.` | O XML do evento ainda não está disponível | Consulte de novo depois que o evento for processado |

### Notificações, pessoas jurídicas e pessoas físicas

Onde: `/v1/companies/{companyId}/notifications`, `/legalpeople` e `/naturalpeople`, status **400**, exceto onde indicado.

| Mensagem (EN) | Português | Ação |
|---|---|---|
| `Company not found` (404, notificações) | Empresa não encontrada | Confira o `companyId` |
| `"Filters" is null or empty array` | `Filters` é nulo ou uma lista vazia | Envie ao menos um evento em `Filters` |
| `"Filters" item "{eventName}" has been already used on other notification` | O evento "`{eventName}`" já é usado em outra notificação | Remova o evento duplicado ou edite a notificação existente |
| `"CreateNotificationEmailResource" is null, empty or not a valid JSON` | O corpo da notificação é nulo, vazio ou não é um JSON válido | Envie um JSON válido |
| `name is null, empty or whitespaces` | `name` é nulo, vazio ou só tem espaços | Informe `name` |
| `email is null, empty or whitespaces` | `email` é nulo, vazio ou só tem espaços | Informe `email` |
| `legal person id is not valid` / `natural person id is not valid` | O id da pessoa jurídica / física não é válido | Confira o `id` na rota |
| `body is null` | O corpo é nulo | Envie o corpo da requisição |

## Erros de formato do JSON

Quando o corpo não pode ser lido, a API responde **400** em `application/problem+json`. A chave de `errors` é o caminho do campo (`$.campo`). Estas mensagens vêm do framework da API e têm sempre o mesmo formato.

| Mensagem (EN) | Português | Causa e ação |
|---|---|---|
| `One or more validation errors occurred.` (campo `title`) | Ocorreram um ou mais erros de validação | Título padrão. Leia o detalhe em `errors` |
| `A non-empty request body is required.` | É obrigatório enviar um corpo não vazio | Envie o JSON no corpo da requisição |
| `The JSON value could not be converted to {Type}. Path: {path} \| LineNumber: {n} \| BytePositionInLine: {n}.` | O valor JSON não pôde ser convertido para `{Type}`. Caminho: `{path}` | O campo tem o tipo errado (texto em campo numérico, por exemplo). Corrija o tipo no `path` indicado |
| `Unable to convert "{valor}" to enum {Enum}.` | Não foi possível converter "`{valor}`" para o enum `{Enum}` | O valor não está na lista permitida do campo. Use um valor da documentação do campo |
| `Unable to convert "{valor}" to boolean.` | Não foi possível converter "`{valor}`" para booleano | Envie `true` ou `false` |
| `Unexpected token {TokenType} for FederalTaxNumber; expected String or Number.` | Token inesperado `{TokenType}` em FederalTaxNumber; esperado texto ou número | Envie `federalTaxNumber` como texto ou número |
| `The {Field} field is required.` | O campo `{Field}` é obrigatório | Informe o campo. Aparece em pessoas jurídicas e físicas (`Name`, `Address`) |
| `'{c}' is an invalid start of a value. Path: {path} ...` | '`{c}`' não pode iniciar um valor. Caminho: `{path}` | JSON malformado. Valide o JSON antes de enviar |

### Versão da API na URL

A resposta é **400** em ProblemDetails com o campo `code` estável.

| `code` | `title` (EN) | Português | Ação |
|---|---|---|---|
| `UnsupportedApiVersion` | `Unsupported API version` | Versão da API não suportada | Use uma versão existente na rota, como `/v1/` ou `/v3/` |
| `InvalidApiVersion` | `Invalid API version` | Versão da API inválida | Corrija o formato da versão na rota |
| `ApiVersionUnspecified` | `Unspecified API version` | Versão da API não informada | Inclua a versão na rota |
| `AmbiguousApiVersion` | `Ambiguous API version` | Versão da API ambígua | Informe uma única versão |

### Erro genérico

| Status | Mensagem (EN) | Português | Ação |
|---|---|---|---|
| 500 | `An error occurred while processing your request.` (campo `title`) | Ocorreu um erro ao processar a requisição | Erro interno. Tente de novo e, se repetir, abra chamado com o `traceId` da resposta |
| 404 | `Not Found` (campo `title`) | Não encontrado | O recurso (PDF ou XML) ainda não existe para a nota. Consulte o `status` da nota |

## Campo flowMessage

O `flowMessage` guarda o motivo da última falha no **processamento assíncrono** da nota. Ele sai no `GET` da nota e no payload do [webhook](../../../webhooks/catalogo-saida/catalogo-saida-nfse.md), e **não** no corpo da resposta de emissão. As tabelas abaixo organizam as mensagens pelo **estágio** em que a falha acontece, que é o "onde" do `flowMessage`.

### Como ler o flowMessage

- O texto é livre e **não tem código de erro estável**. O `status` e o `flowStatus` da nota são os campos para decidir o que fazer. O `flowMessage` explica a causa.
- Quando a prefeitura recusa a nota, o `flowMessage` traz o texto da prefeitura, no idioma dela. Esse texto não está neste catálogo.
- A mensagem pode ter um prefixo e um sufixo da plataforma. Por exemplo, ao esgotar as tentativas, a plataforma acrescenta o último erro: `max retry reached on send batch stage last error was '...'`.

### Esgotamento de tentativas (max retry)

Quando uma etapa tenta por cerca de 23 horas sem resposta definitiva, a plataforma para e grava `max retry reached on {etapa} stage`. O evento do webhook passa a ser `issued_failed` ou `cancelled_failed`.

| Mensagem (EN) | Português | Onde (estágio) |
|---|---|---|
| `max retry reached on define borrower details stage` | Limite de tentativas na etapa de definição do tomador | Emissão: dados do tomador |
| `max retry reached on set calculate taxes stage` | Limite de tentativas na etapa de cálculo de impostos | Emissão: cálculo de impostos |
| `max retry reached on set RPS number stage` | Limite de tentativas na etapa de numeração do RPS | Emissão: numeração do RPS |
| `max retry reached on send batch stage` | Limite de tentativas na etapa de envio do lote | Emissão: envio à prefeitura |
| `max retry reached on check batch stage` | Limite de tentativas na etapa de consulta do lote | Emissão: consulta do resultado |
| `max retry reached on send to cancel stage` | Limite de tentativas na etapa de envio do cancelamento | Cancelamento: envio |
| `max retry reached on check batch cancel stage` | Limite de tentativas na etapa de consulta do cancelamento | Cancelamento: consulta do resultado |
| `max retry reached sending event to ADN` | Limite de tentativas ao enviar o evento ao ADN | Cancelamento por evento (ambiente Nacional) |
| `max retry reached on download stage` | Limite de tentativas na etapa de download | Download de PDF ou XML. A nota continua emitida |

**Ação.** Confira na prefeitura se a nota foi emitida. Se não foi, envie a nota para re-emissão. O passo a passo está em [Erro Max Retry Reached On Send Batch Stage](../../../../duvidas-frequentes/erros/erro-max-retry-reached-batch-stage.md). Na etapa de download, a nota já está emitida. Peça um novo link de download.

### Mensagens que envolvem outra mensagem

| Mensagem (EN) | Português | Causa |
|---|---|---|
| `{mensagem} last error was '{erro anterior}'` | `{mensagem}`; o último erro foi '`{erro anterior}`' | A plataforma acrescentou o erro da tentativa anterior. Leia o trecho entre aspas para a causa real |
| `Error: {motivo}` | Erro: `{motivo}` | A numeração do RPS falhou de forma definitiva. O motivo vem do cadastro da empresa |

### Dados da nota e cadastro da empresa

| Mensagem (EN) | Português | Causa e ação |
|---|---|---|
| `city code is null or empty` | O código da cidade é nulo ou vazio | Falta o código IBGE da cidade. Corrija o cadastro da empresa e reprocesse |
| `prefecture not found for city code {cityCode}` | Prefeitura não encontrada para o código de cidade `{cityCode}` | O município não tem integração ativa. Veja as [prefeituras integradas](/docs/prefeituras-integradas/) |
| `failed to resolve the company certificate` | Falha ao obter o certificado da empresa | O certificado digital está ausente, vencido ou inválido. Reenvie o certificado A1 da empresa |
| `service invoice with the same external id already exists` | Já existe nota com o mesmo identificador externo | Use outro `externalId` ou consulte a nota existente |
| `service invoice with rps number ({RpsNumber}) already exists` | Já existe nota com o número de RPS (`{RpsNumber}`) | Use o próximo RPS livre |
| `service invoice with external id ({ExternalId}) already exists` | Já existe nota com o identificador externo (`{ExternalId}`) | Consulte a nota existente |
| `service invoice with rps Serial ({RpsSerialNumber}) and rps number ({RpsNumber}) already exists in invoices: {ids}` | Já existe nota com a série de RPS (`{RpsSerialNumber}`) e o número (`{RpsNumber}`) nas notas: `{ids}` | O RPS informado manualmente está ocupado. Use outro número |
| `Certificate resolution failed permanently for invoice {invoiceId}, company {companyId}: {Status} {Value}` | Falha definitiva ao resolver o certificado da nota `{invoiceId}`, empresa `{companyId}` | O certificado da empresa não pôde ser usado. Verifique o certificado e reprocesse |

### Cálculo de impostos

| Mensagem (EN) | Português | Causa e ação |
|---|---|---|
| `city service code '{CityServiceCode}' was not found for city code '{cityCode}' for calculate taxes` | O código de serviço '`{CityServiceCode}`' não foi encontrado para a cidade '`{cityCode}`' no cálculo de impostos | O `cityServiceCode` não existe para o município. Confira o código na lista da cidade |
| `provider federal tax number '{FederalTaxNumber}' is not a valid CNPJ for tax calculation` | O CNPJ do prestador '`{FederalTaxNumber}`' não é válido para o cálculo de impostos | Corrija o CNPJ da empresa |
| `tax service lookup failed ({Status}) for city service code '{CityServiceCode}' and city code '{cityCode}'` | A consulta do serviço tributário falhou (`{Status}`) para o código '`{CityServiceCode}`' e a cidade '`{cityCode}`' | Reprocesse a nota. Se repetir, abra chamado |
| `ibpt code '{federalServiceCode}' was not found for state '{UF}' to calculate approximate tax burden` | O código IBPT '`{federalServiceCode}`' não foi encontrado para a UF '`{UF}`' no cálculo da carga tributária aproximada | Confira o código de serviço federal ou informe `approximateTax` |
| `Failed to get the cityServiceCode` | Falha ao obter o `cityServiceCode` | Informe o `cityServiceCode` na emissão |

### Validação antes do envio à prefeitura

Estas mensagens aparecem quando a plataforma recusa o dado **antes** de enviar à prefeitura.

| Provedor | Mensagem (EN) | Português | Ação |
|---|---|---|---|
| Nacional (ADN), Cidade360, SilTecnologia | `Invalid RpsSerialNumber for National Proxy` | Série de RPS inválida para o provedor Nacional | Corrija `rpsSerialNumber` |
| Betha Cloud | `Invalid RpsSerialNumber for Betha Cloud Proxy` | Série de RPS inválida para o provedor Betha Cloud | Corrija `rpsSerialNumber` |
| Nacional | `Invalid CityServiceCode for National Proxy` | Código de serviço da cidade inválido para o provedor Nacional | Corrija `cityServiceCode` |
| Nacional | `Invalid cTribNac source value '{valor}': must be exactly 6 numeric digits ...` | Valor de origem do cTribNac '`{valor}`' inválido: deve ter exatamente 6 dígitos numéricos | Informe `federalServiceCode` com 6 dígitos (por exemplo `050801`) ou `cityServiceCode` no formato `050801.050` |
| Nacional | `DeductionDocument must have exactly one identifier set: ...` | O documento de dedução deve ter exatamente um identificador | Informe um só identificador por documento de dedução |
| Nacional | `DeductionDocument.{Campo} is required ...` | O campo `{Campo}` do documento de dedução é obrigatório | Preencha o campo indicado |
| SIGISS | `The value of field {campo} is invalid: expected 6 numeric digits, got '{valor}'.` | O valor do campo `{campo}` é inválido: esperados 6 dígitos numéricos | Informe `ibsCbs.classCode` e `ibsCbs.operationIndicator` com 6 dígitos |
| Barueri | `{campo} lenght must be less than {N} characters` | `{campo}` deve ter menos de `{N}` caracteres | Reduza o tamanho do campo |
| Barueri | `{campo} must not exceed {N} characters` | `{campo}` não pode passar de `{N}` caracteres | Reduza o tamanho do campo |
| Barueri | `location is required when ibsCbs.operationIndicator is '{op}' ...` | `location` é obrigatório quando `ibsCbs.operationIndicator` é '`{op}`' (operação com imóvel) | Informe rua, número, bairro, cidade, UF e CEP do local da prestação |
| Barueri | `location.city.code is required for a service rendered in Brazil ...` | `location.city.code` é obrigatório para serviço prestado no Brasil | Informe o código IBGE da cidade da prestação |
| Barueri | `location.country is required for a service rendered abroad ...` | `location.country` é obrigatório para serviço prestado no exterior | Informe o país do local da prestação |
| Barueri | `location.country is not mapped in the Barueri country table ...` | `location.country` não consta na tabela de países de Barueri | Use um país aceito pela prefeitura (ISO 3166-1 alfa-3) |
| AVMB, Florianópolis | `Token cannot be null` | O token não pode ser nulo | Cadastre o token de integração da prefeitura na empresa |
| EL Nacional | `Invalid AuthIssueValue for EL National Proxy: the integration token is required on every request` | Valor de autenticação inválido: o token de integração é obrigatório em toda requisição | Cadastre o token de integração da empresa |
| Cidade360 | `Cancellation is not available via webservice for this provider.` | O cancelamento não está disponível por webservice neste provedor | Cancele a nota no portal da prefeitura |

### Autenticação e acesso na prefeitura

| Provedor | Mensagem (EN) | Português | Ação |
|---|---|---|---|
| Nacional e herdeiros | `{statusCode} - Access is denied.` | `{statusCode}` - Acesso negado | A prefeitura negou o acesso. Verifique o certificado digital e as credenciais da empresa |
| EL Nacional | `EL rejected the integration token (HTTP {code}). Generate a new token in the city portal (Configurações → Integração) and update the company registration.` | O EL recusou o token de integração (HTTP `{code}`). Gere um novo token no portal da cidade (Configurações → Integração) e atualize o cadastro da empresa | Gere o novo token e atualize a empresa |
| SIGISSWeb | `Authentication Failure` | Falha de autenticação | Confira o usuário e a senha da prefeitura no cadastro da empresa |

### Divergência entre a nota e a resposta da prefeitura

A prefeitura respondeu, mas os dados não conferem com a nota enviada. Confira a nota no portal da prefeitura antes de reprocessar.

| Provedor | Mensagem (EN) | Português |
|---|---|---|
| ABRASF 2.01, BHISS, João Pessoa, Paulistana, Vitória | `Rps does not match this borrower` | O RPS não corresponde a este tomador |
| Osasco | `Rps does not match this invoice` | O RPS não corresponde a esta nota |
| Lexsom, Pronim | `rps number does not match invoice` | O número do RPS não corresponde à nota |
| EL | `Divergence detected: borrower tax number in the response does not match the issued invoice` | Divergência: o CPF/CNPJ do tomador na resposta não corresponde à nota emitida |
| EL | `Divergence detected: services amount in the response does not match the issued invoice` | Divergência: o valor dos serviços na resposta não corresponde à nota emitida |
| SIGISS | `Borrower CNPJ mismatch: expected {esperado}, but prefecture returned {recebido}` | CNPJ do tomador divergente: esperado `{esperado}`, a prefeitura devolveu `{recebido}` |
| SIGISS | `Service amount mismatch: expected {esperado}, but prefecture returned {recebido}` | Valor do serviço divergente: esperado `{esperado}`, a prefeitura devolveu `{recebido}` |
| SIGISS | `RPS number mismatch: expected {esperado}, but prefecture returned {recebido}` | Número do RPS divergente: esperado `{esperado}`, a prefeitura devolveu `{recebido}` |

### Resposta vazia ou ilegível da prefeitura

| Provedor | Mensagem (EN) | Português |
|---|---|---|
| Paulistana (SP) | `Empty response from prefecture webservice` | Resposta vazia do webservice da prefeitura |
| EL Nacional | `Empty or invalid response from EL` | Resposta vazia ou inválida do EL |
| EL Nacional | `Response from EL has no idDPS` | A resposta do EL não tem idDPS |
| EL Nacional | `Unreadable nfseXmlGZipB64 returned by EL for access key {chave}` | nfseXmlGZipB64 ilegível devolvido pelo EL para a chave de acesso `{chave}` |
| GIAP | `cancel xml is null` | O XML de cancelamento é nulo |
| SMARAPD | `RPS not found in the response` | RPS não encontrado na resposta |

**Ação.** Consulte a nota no portal da prefeitura. Se a nota existe, aguarde a sincronização. Se não existe, reprocesse.

### Motor de cálculo IBS/CBS

Algumas mensagens de IBS/CBS começam em português e terminam em inglês. O prefixo é `Falha no pré-cálculo do IBS/CBS (Tax Engine): `. Provedores: Elotech, SilTecnologia e TINUS.

| Trecho em inglês | Português |
|---|---|
| `Tax Engine timed out.` | O motor de cálculo excedeu o tempo limite |
| `Tax Engine transport failure.` | Falha de comunicação com o motor de cálculo |
| `Tax Engine returned HTTP {statusCode}[ - {detalhe}]` | O motor de cálculo respondeu HTTP `{statusCode}` |
| `Tax Engine returned an empty success body.` | O motor de cálculo respondeu sucesso com corpo vazio |
| `Tax Engine returned a malformed JSON success body.` | O motor de cálculo respondeu sucesso com um JSON malformado |

**Ação.** Reprocesse a nota. Se o erro repetir, abra chamado com o `id` da nota.

### Substituição e eventos não suportados

| Mensagem (EN) | Português | Ação |
|---|---|---|
| `Substitution not supported for provider {Provedor}. ...` | Substituição não suportada para o provedor `{Provedor}` | Cancele a nota original e emita uma nova no portal da prefeitura |
| `EnviarEvento not supported by this proxy` | O envio de evento não é suportado por este provedor | O cancelamento por evento só existe no ambiente Nacional |
| `unsupported event type {EventType}` | Tipo de evento não suportado: `{EventType}` | Use um tipo de evento aceito |
| `missing event detail for event type {EventType}` | Falta o detalhe do evento do tipo `{EventType}` | Envie o detalhe exigido pelo tipo de evento |

### Mensagens técnicas de exceção

Alguns erros vêm direto de uma exceção do sistema. O texto varia, fica em inglês e **não** orienta uma correção.

| Padrão (EN) | Exemplo | Ação |
|---|---|---|
| `[999] {texto}` | `[999] Data at the root level is invalid. Line 1, position 1.` | A resposta da prefeitura não é um XML válido. Reprocesse. Se repetir, abra chamado |
| `{prefixo em português}: {texto}` | `[E999] Erro ao deserializar resposta XML: Data at the root level is invalid` | Idem |
| `EnviarLote failed with {Exceção}: {texto}` / `CancelarNotaFiscal failed with {Exceção}: {texto}` | `EnviarLote failed with ...` | Falha no envio ou no cancelamento. Reprocesse. Se repetir, abra chamado |
| `Nullable object must have a value.`, `Sequence contains no elements` | Idem | Dado ausente na nota. Revise o payload e abra chamado se tudo estiver preenchido |

### Ambiente de testes

No ambiente de desenvolvimento, uma descrição com o gatilho de erro aleatório devolve `[E998] Random error on SendBatch.` ou `[E999] Random error on CheckBatch.`. Veja [Como simular erro de processamento](./como-simular-erro-de-processamento-nfse-ambiente-de-testes.md).

## Veja também

- [Cenários de erro 400 na emissão de NFS-e](./cenarios-de-badrequest-na-emissao.md)
- [Solução de erros 400 na emissão de NFS-e](./solucao-de-erros-400-na-emissao.md)
- [Tipos de retorno de status das requisições HTTPS](./tipos-de-retorno-de-status-das-requisicoes-https.md)
- [Erro Max Retry Reached On Send Batch Stage](../../../../duvidas-frequentes/erros/erro-max-retry-reached-batch-stage.md)
- [Caracteres especiais nos campos de texto da NFS-e](./caracteres-especiais-pt-br.md)

## Para IA / LLMs

- **Cobertura:** mensagens de erro da API de NFS-e v1, em respostas HTTP síncronas e no campo `flowMessage` do fluxo assíncrono.
- **Não parafrasear:** a coluna "Mensagem (EN)" é **literal**. Reproduza o texto original ao responder. A coluna "Português" é uma tradução de referência desta documentação, não texto retornado pela API.
- **Idioma:** a API responde em inglês. Há mensagens em português (de prefeituras e de integrações novas) e mensagens com os dois idiomas. Não há escolha de idioma na resposta.
- **Código de erro:** quase todas as mensagens **não** têm código estável. Só `UnsupportedApiVersion`, `InvalidApiVersion`, `ApiVersionUnspecified` e `AmbiguousApiVersion` têm `code`. Use o status HTTP, o `status` e o `flowStatus` da nota para decidir.
- **Texto da prefeitura:** o `flowMessage` pode trazer o texto da prefeitura sem alteração. Esse texto não está neste catálogo.
- **Pré-requisitos:** [Tipos de retorno de status das requisições HTTPS](./tipos-de-retorno-de-status-das-requisicoes-https.md).
- **Atualizado:** 2026-10-09.