> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notasx.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Um formato só para todos os erros. Trate pelo código.

Todo erro da API tem o mesmo corpo:

```json theme={null}
{"erro": {"codigo": "cnpj_divergente", "mensagem": "O Certificado não é do CNPJ deste Prestador."}}
```

* **`codigo`** é estável. Use-o no seu código.
* **`mensagem`** é para humanos e pode mudar. Não compare com ela.
* O status HTTP segue o código (veja a tabela).

## Todos os códigos

| Código | HTTP | Mensagem | Onde |
| - | - | - | - |
| `nao_autenticado` | 401 | Credencial ausente, inválida ou revogada. | Todas as rotas |
| `nao_encontrado` | 404 | Chave de API não encontrada. | `DELETE /v1/chaves-api/{chave_id}` |
| `nao_encontrado` | 404 | Nota não encontrada. | `GET /v1/notas/{nota_id}` `GET /v1/notas/{nota_id}/xml` |
| `nao_encontrado` | 404 | Prestador não encontrado. | `POST /v1/notas` `GET /v1/prestadores/{prestador_id}` `POST /v1/prestadores/{prestador_id}/ativar-producao` `POST /v1/prestadores/{prestador_id}/certificado` |
| `nao_encontrado` | 404 | Webhook não configurado. | `GET /v1/webhook` |
| `xml_indisponivel` | 404 | O XML desta Nota ainda não está disponível. | `GET /v1/notas/{nota_id}/xml` |
| `cnpj_ja_cadastrado` | 409 | Este CNPJ já está cadastrado no NotasX. | `POST /v1/prestadores` |
| `arquivo_grande` | 413 | O .pfx passa de 1 MB. | `POST /v1/prestadores/{prestador_id}/certificado` |
| `certificado_invalido` | 422 | Não foi possível abrir o .pfx com essa senha. | `POST /v1/prestadores/{prestador_id}/certificado` |
| `certificado_vencido` | 422 | O Certificado está vencido. | `POST /v1/prestadores/{prestador_id}/certificado` |
| `cnpj_divergente` | 422 | O Certificado não é do CNPJ deste Prestador. | `POST /v1/prestadores/{prestador_id}/certificado` |
| `requisicao_invalida` | 422 | Lista os campos inválidos (varia). | Todas as rotas |
| `sem_certificado_valido` | 422 | Envie um Certificado válido antes de ativar a produção. | `POST /v1/prestadores/{prestador_id}/ativar-producao` |
| `cota_esgotada` | 429 | A Cota do mês acabou. | `POST /v1/notas` |
| `limite_de_requisicoes` | 429 | Muitas requisições; tente de novo em instantes. | Todas as rotas |
| `storage_indisponivel` | 502 | Não foi possível guardar o Certificado; tente de novo. | `POST /v1/prestadores/{prestador_id}/certificado` |

## Como reagir

| Situação | O que fazer |
| - | - |
| `401` | Confira a Chave de API. Se foi revogada, crie outra. Não repita automaticamente. |
| `404` | O recurso não existe **ou** é de um Prestador sem vínculo com a sua Conta. |
| `409` | Conflito com o estado atual; repetir não resolve. |
| `422` | Corrija o pedido. `requisicao_invalida` lista os campos com problema na `mensagem`. |
| `429` | Espere os segundos do header `Retry-After` e tente de novo. |
| `5xx` | Falha temporária. Repita com espera crescente (e, em `POST /v1/notas`, com o mesmo `Idempotency-Key`). |

> [!NOTE]
>
> Erros da API são diferentes do resultado da emissão. Uma Nota criada com sucesso (`202`) pode terminar
> `rejeitada` ou `falhou`: isso aparece no `status` da Nota, não num erro HTTP. Veja
> [Ciclo da Nota](https://docs.notasx.com.br/conceitos/ciclo-da-nota.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.