# Tratamento de erros

> Identifique os códigos e saiba como reagir.

Fonte: https://www.nextapi.com.br/docs/erros

Use o status HTTP para identificar o resultado geral e o campo `code`, quando presente, para decidir como sua aplicação deve agir.

```json
{
  "status": "Erro",
  "code": 1003,
  "message": "O número de requisições por minuto excedeu o limite do plano."
}
```

| Código | Significado | O que fazer |
| --- | --- | --- |
| `1000` | Registro não encontrado | Confira o identificador e trate a ausência de dado. |
| `1001` | Token não informado | Envie Authorization no cabeçalho. |
| `1002` | Token inválido | Verifique a chave e a configuração da integração. |
| `1003` | Limite por minuto excedido | Diminua a frequência e aguarde antes de tentar novamente. |
| `1004` | Créditos esgotados | Consulte o saldo e ajuste o plano ou os créditos. |
| `1005` | Tempo real não permitido | Verifique as permissões do workspace. |
| `1006` | Saldo insuficiente para tempo real | Confira o saldo necessário para a busca externa. |
| `1007` | CEP inválido | Confira o formato e os dígitos do CEP. |
| `1008` | Parâmetros geoespaciais ausentes | Informe latitude, longitude e raioMetro. |
| `1009` | Latitude inválida | Use um valor entre -90 e 90. |
| `1010` | Longitude inválida | Use um valor entre -180 e 180. |
| `1011` | Raio inválido | Informe um raio maior que zero, na unidade exigida pelo endpoint. |
| `1012` | Recurso restrito a planos pagos | Confira o plano necessário para a operação. |
| `1013` | Filtros incompatíveis | Não combine q com logradouro. |
| `1014` | Falha do provedor externo | Tente novamente após uma espera, com limite de tentativas. |
| `9999` | Erro não mapeado | Leia a mensagem e registre o contexto sem incluir seu token. |

## Status HTTP

Os endpoints podem responder com estes status:

- `400`: parâmetros ou permissões inválidos.
- `401`: token inválido.
- `404`: registro ausente.
- `405`: falta de créditos.
- `429`: excesso de requisições.
- `500`: falha interna.
- `502`: falha de provedor externo.

As respostas documentadas por operação estão na referência. Falhas de autenticação e de limite podem ocorrer antes da execução do endpoint, mesmo quando não aparecem na lista de respostas do OpenAPI.

## Retentativas

- Não repita automaticamente erros de token, parâmetros ou falta de saldo.
- Para erros transitórios, use espera progressiva e limite de tentativas. Se houver `Retry-After`, respeite-o.
- Uma resposta de erro pode não ter corpo JSON. Verifique o tipo de conteúdo e trate respostas vazias.
- Após um timeout, o servidor pode já ter processado a consulta. Repetir a operação pode gerar novo consumo de créditos.

Se precisar de ajuda, envie à equipe o endpoint, o horário e o código do erro. Não envie seu token.