# Créditos e limites

> Entenda o consumo, o saldo e as permissões do plano.

Fonte: https://www.nextapi.com.br/docs/creditos-e-limites

Créditos medem o consumo de consultas; o limite de requisições por minuto controla a frequência de acesso. Ter saldo disponível não elimina o limite de frequência nem libera automaticamente todos os recursos.

## Consulte seu saldo

```bash
curl 'https://api.nextapi.com.br/v1/credits' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Accept: application/json'
```

Esse endpoint consome **0 créditos** e pode ser chamado com saldo zerado, mantendo a exigência de autenticação e o limite de requisições.

| Campo | Significado |
| --- | --- |
| `planCredits.remaining` | Créditos restantes da assinatura. |
| `extraCredits.remaining` | Créditos avulsos disponíveis. |
| `totalRemainingCredits` | Soma dos saldos disponíveis. |
| `limits.requestsPerMinute` | Limite de requisições por minuto. |
| `limits.canLiveSearch` | Indica se o workspace pode realizar consulta em tempo real. O saldo necessário também é validado ao consultar. |

## Custos por tipo de consulta

| Consulta | Consumo |
| --- | --- |
| CEP por número | 1 crédito no gratuito; isenta nos planos pagos. |
| CNPJ e Simples Nacional em cache | 1 crédito por consulta. |
| CNPJ e Simples Nacional com busca em tempo real | 15 créditos quando a busca externa é realizada. |
| Pesquisa avançada e geoespacial de CEPs | 2 créditos por consulta; planos pagos. |
| CNPJ e Simples em lote | 1 crédito por registro localizado; até 100 CNPJs por requisição; planos pagos. |
| Empresas, CNAEs, estados e municípios | 1 crédito por consulta; planos pagos. |
| Inscrições Estaduais | 1 crédito por consulta. |

Consulte também a descrição do endpoint na [referência](https://www.nextapi.com.br/docs/referencia). Não trate créditos como uma quantidade fixa de consultas: o custo depende da operação e da origem do dado.

## Quando o limite é atingido

HTTP `429` com código `1003` indica excesso de requisições. Distribua as chamadas ao longo do tempo e use retentativas com espera progressiva. Falta de saldo pode retornar HTTP `405` com código `1004`; para busca em tempo real, o código `1006` indica saldo insuficiente.

Os cabeçalhos `RemainingCredits`, `HasCredits` e `PaidPlan` ajudam a acompanhar o estado da assinatura. Para consultar também créditos avulsos, use `/v1/credits`.

[Compare os planos](https://www.nextapi.com.br/#pricing) considerando seus endpoints, volume mensal e picos por minuto.