> ## 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 respostas

> Como a API da Spedy sinaliza erros e como tratá-los.

A API usa códigos de status HTTP para indicar o resultado de cada requisição.
Respostas de sucesso (`2xx`) trazem o recurso criado, atualizado ou
consultado. Respostas de erro trazem uma mensagem descrevendo o problema no
corpo — consulte o endpoint específico na [Referência da
API](/pages/reference/introducao) para o formato exato do corpo de erro daquela
chamada.

## Códigos HTTP documentados hoje

| Código | Significado       | Quando ocorre                                                                                        |
| ------ | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `400`  | Bad Request       | Erro de validação de campos ou violação de uma regra de negócio (ex.: CNPJ inválido, item sem valor) |
| `403`  | Forbidden         | Chave de API (`X-Api-Key`) inválida, ausente ou do ambiente errado                                   |
| `429`  | Too Many Requests | Limite de requisições excedido — veja [Rate limit](/pages/start/rate-limit)                          |

## Como tratar

1. **Trate `400` como definitivo** para aquela requisição: corrija os dados
   antes de tentar de novo. Reenviar sem alterar o payload provavelmente
   resulta no mesmo erro.
2. **Trate `403` como um problema de configuração**: confira se a chave está
   correta e se pertence ao ambiente (sandbox ou produção) que você está
   chamando. Veja [Autenticação](/pages/start/autenticacao).
3. **Trate `429` com espera e retry** — nunca insista imediatamente. Veja
   [Rate limit](/pages/start/rate-limit) para um exemplo de backoff.
4. **Lembre-se que `2xx` na emissão não é autorização.** Para NF-e, NFC-e e
   NFS-e, a emissão é assíncrona: um `2xx` confirma que a solicitação foi
   aceita para processamento, não que a nota foi autorizada pela SEFAZ ou
   prefeitura. Acompanhe o resultado real por webhook ou consulta de status.

## Rejeições fiscais

Erros de validação da própria SEFAZ ou prefeitura (ex.: CFOP incompatível,
NCM inválido) não são o mesmo que um `400` da API — a requisição de emissão
pode retornar `2xx` e, ainda assim, a nota ser rejeitada de forma assíncrona.

Quando isso acontece, a nota fica com o status `rejected` e o motivo da
rejeição vem no objeto **`processingDetail`** da nota, nos campos `code` e
`message` (rejeições geradas pela própria Spedy usam o prefixo `SPD` no
`code`). Leia esse objeto consultando a nota ou pelo evento de
[webhook](/pages/webhooks/eventos-e-payload).

Veja a lista de rejeições e como tratá-las em [Erros e rejeições
SEFAZ](/pages/reference/erros-e-rejeicoes).