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. 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.

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
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
Campo flowMessage da nota	Texto livre, no GET da nota e no payload do webhook	Veja Campo flowMessage

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.

nota

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

atenção

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, 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. 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
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.

Veja também

• Cenários de erro 400 na emissão de NFS-e
• Solução de erros 400 na emissão de NFS-e
• Tipos de retorno de status das requisições HTTPS
• Erro Max Retry Reached On Send Batch Stage
• Caracteres especiais nos campos de texto da NFS-e

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.
• Atualizado: 2026-10-09.