Erros e rejeições

Esta página cobre dois tipos diferentes de erro que você pode encontrar ao integrar com a API da Spedy: erros HTTP da API (a chamada em si falhou) e rejeições fiscais (a chamada funcionou, mas a SEFAZ ou a prefeitura recusou a nota). Tratá-los como a mesma coisa é a causa mais comum de integrações que fazem retry do jeito errado — veja a diferença logo abaixo.

Erros HTTP da API

Erros HTTP acontecem na própria chamada — a requisição não foi aceita para processamento. A resposta traz uma mensagem de erro no corpo explicando o problema.

Código	Significado	Como agir
`400`	Validação de campos ou violação de uma regra de negócio (ex.: CNPJ inválido, item sem valor)	Definitivo para aquela requisição — corrija os dados antes de reenviar. Reenviar sem alterar o payload resulta no mesmo erro.
`403`	Chave de API (`X-Api-Key`) inválida, ausente ou do ambiente errado	Problema de configuração — confira a chave e o ambiente (sandbox ou produção). Veja Autenticação.
`429`	Limite de requisições excedido	Espere e faça retry com backoff — nunca insista imediatamente. Veja Rate limit.

O corpo do erro ainda não tem um schema padronizado no OpenAPI — a mensagem descreve o problema, mas o formato exato pode variar por endpoint. Os códigos 401, 404, 422 e 500 também ainda não são padronizados pela API; serão adicionados e documentados aqui conforme forem padronizados. Trate qualquer código fora da lista acima como um erro genérico até a padronização ser publicada. Veja também Erros e respostas.

Rejeições fiscais (SEFAZ/Prefeitura)

Uma rejeição fiscal é diferente de um erro HTTP: a requisição de emissão foi aceita (resposta 2xx, nota criada com status enqueued), mas a autoridade fiscal — SEFAZ ou prefeitura — recusou a nota durante o processamento assíncrono. Isso nunca chega como um erro HTTP; a nota é atualizada para status: "rejected" e o motivo fica em processingDetail.

Confira o resultado por webhook (invoice.rejected ou invoice.status_changed) ou consultando a nota (GET /v1/{modelo}-invoices/{id}). Veja Ciclo de vida da nota para a máquina de estados completa.

O objeto `processingDetail`

Toda nota traz o resultado do último processamento (emissão, cancelamento, carta de correção etc.) no campo processingDetail:

Campo	Descrição
`status`	`InvoiceProcessingStatus` — `success`, `processing` ou `failed`. Indica se o evento na fila foi executado, não se a nota foi autorizada: uma nota rejeitada tem `processingDetail.status: "success"`, porque o processamento em si funcionou normalmente.
`message`	Mensagem descritiva do resultado — para rejeições da SEFAZ/prefeitura, costuma trazer o texto original da autoridade.
`code`	Código do resultado — da autoridade fiscal, ou da Spedy (prefixo `SPD`) quando a recusa é interna.
`on`	Data/hora do processamento.

Exemplo de nota rejeitada (o code abaixo é ilustrativo):

{
  "id": "833e8e0e-3bda-4394-ab70-5edf4ee70988",
  "status": "rejected",
  "processingDetail": {
    "status": "success",
    "message": "Rejeicao: CFOP incompativel com a natureza da operacao",
    "code": "215",
    "on": "2026-08-03T18:35:38.443559"
  }
}

Rejeição da SEFAZ vs. rejeição interna da Spedy

O code diz a origem, com o mesmo formato em processingDetail:

SEFAZ/Prefeitura — a nota chegou até a autoridade fiscal e foi recusada por ela (schema, regra de negócio, cadastro divergente etc.). O code traz o código da própria autoridade (numérico; ou E9999 para uma rejeição genérica sem código mapeado). A causa e a solução estão no processingDetail.message — a fonte canônica é a tabela oficial de rejeições da SEFAZ da UF/município.
Spedy — validações e estados que a Spedy resolve sem transmitir (ou antes de ter o retorno definitivo) usam o prefixo SPD no code. Estão documentados abaixo.

Códigos internos da Spedy (`SPD`)

Quando o code começa com SPD, a recusa (ou o estado transitório) veio da própria Spedy, não da autoridade fiscal:

`code`	Significado	Tipo	O que fazer
`SPD001`	RPS/nota ainda em processamento no provedor (NFS-e).	Transitório	Aguarde e consulte de novo (`check-status`) — não reemita.
`SPD002`	Cancelamento em processamento.	Transitório	Aguarde a confirmação; não repita o cancelamento em loop.
`SPD003`	Erro de validação do payload antes do envio (campo obrigatório, formato inválido, campo fora de ordem).	Definitivo	Corrija o payload e reemita.
`SPD004`	A nota já está autorizada — a operação é incompatível com o estado atual.	Definitivo	Não reemita; use a nota já autorizada.
`SPD005`	Serviço/operação não suportado nesse cenário (ex.: recurso indisponível para o provedor municipal).	Definitivo	A operação não se aplica; veja o guia do modelo para a alternativa.
`SPD006`	Nota ainda não processada (enfileirada) — resultado ainda não disponível.	Transitório	Acompanhe por webhook ou `check-status` até o estado final.
`SPD998`	Erro inesperado da Spedy (não é uma rejeição da autoridade fiscal).	Interno	A Spedy trata o caso internamente, sem duplicar a nota. Acompanhe o estado final por webhook/consulta; se persistir, reporte ao suporte.
`SPD999`	Erro de comunicação com a SEFAZ/prefeitura.	Transitório	A Spedy faz retentativas automáticas — você não precisa reemitir. Acompanhe o resultado por webhook/consulta.

SPD998 e SPD999 são erros técnicos, não rejeições da autoridade fiscal — a nota não foi necessariamente recusada. Não reemita por conta própria ao receber esses códigos: a Spedy já reprocessa o que for cabível, e reemitir manualmente pode gerar nota duplicada. Acompanhe o estado final da nota por webhook ou consulta.

Recebeu uma rejeição da autoridade (sem prefixo SPD) que não entendeu? O processingDetail.message traz o texto original da SEFAZ/prefeitura — é a fonte mais confiável. Encaminhe o code e o message ao suporte da Spedy se precisar de ajuda para interpretar.

Veja também

Erros e respostas — códigos HTTP da API.
Ciclo de vida da nota — estados da nota, incluindo rejected, e como acompanhar transições.

Visão geral

Endpoints

Erros e rejeições

Erros HTTP da API

Rejeições fiscais (SEFAZ/Prefeitura)

O objeto `processingDetail`

Rejeição da SEFAZ vs. rejeição interna da Spedy

Códigos internos da Spedy (`SPD`)

Veja também

​Erros HTTP da API

​Rejeições fiscais (SEFAZ/Prefeitura)

​O objeto processingDetail

​Rejeição da SEFAZ vs. rejeição interna da Spedy

​Códigos internos da Spedy (SPD)

​Veja também

Erros HTTP da API

Rejeições fiscais (SEFAZ/Prefeitura)

O objeto `processingDetail`

Rejeição da SEFAZ vs. rejeição interna da Spedy

Códigos internos da Spedy (`SPD`)

Veja também