> ## Documentation Index > Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Erros e rejeições > Erros HTTP da API, rejeições fiscais e os códigos internos da Spedy (SPD). 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](/pages/start/autenticacao). | | `429` | Limite de requisições excedido | Espere e faça retry com backoff — nunca insista imediatamente. Veja [Rate limit](/pages/start/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](/pages/start/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](/pages/webhooks/visao-geral) (`invoice.rejected` ou `invoice.status_changed`) ou consultando a nota (`GET /v1/{modelo}-invoices/{id}`). Veja [Ciclo de vida da nota](/pages/guides/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): ```json theme={null} { "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](/pages/start/erros-e-respostas) — códigos HTTP da API. * [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota) — estados da nota, incluindo `rejected`, e como acompanhar transições.