---
title: "Créditos, franquia e rate limit"
description: "Quanto custa cada operação em créditos, como funciona a franquia mensal com hard cap, o que acontece nos limites de requisições por minuto e como ler GET /v1/usage."
canonical: "https://cnpj.ia.br/docs/creditos-e-limites"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# Créditos, franquia e rate limit

Quanto custa cada operação em créditos, como funciona a franquia mensal com hard cap, o que acontece nos limites de requisições por minuto e como ler GET /v1/usage.

Tudo custa em créditos, e você sabe o custo antes de chamar: a consulta `basic` custa 1, a `full` 6, a busca 1 por empresa retornada, e erros custam 0. Cada plano dá uma franquia mensal e um limite de requisições por minuto; quando a franquia acaba a API para de responder com `402`, e nada é cobrado sem uma ação sua.

## Pesos por operação

| Operação | Créditos |
| --- | --- |
| `GET /v1/cnpjs/{cnpj}?profile=basic` | 1 |
| `GET /v1/cnpjs/{cnpj}?profile=full` | 6 |
| `GET /v1/cnpjs` (busca) | 1 por empresa retornada, até 20 por página; página vazia custa 0 |
| `POST /v1/filters/generate` | 1 por chamada |
| `GET /v1/usage` | 0 |
| `GET /v1/status` | 0, sem chave |
| `GET /v1/demo` | 0, sem chave |
| Qualquer erro (4xx, 5xx) | 0 |

Só respostas `200` são cobradas. Uma consulta `full` a uma empresa com pedido de remoção ativo (`meta.suppressed: true`) custa 1 crédito, porque os contatos não são entregues.

## Franquia por plano

| Plano | Créditos por mês | Requisições por minuto | Busca |
| --- | --- | --- | --- |
| Free | 60 | 3 | não |
| Starter | 15000 | 30 | sim |
| Pro | 100000 | 120 | sim |
| Business | 500000 | 300 | sim |
| Scale | 3000000 | 600 | sim |

A franquia renova no primeiro dia do mês-calendário e não acumula: crédito não usado em um mês não passa para o seguinte. No Free a chave nasce com 15 créditos e a verificação do e-mail libera os 60 do mês. Preços e a calculadora de custo estão em [`/precos`](https://cnpj.ia.br/precos); a mesma tabela em Markdown está em [`/pricing.md`](https://cnpj.ia.br/pricing.md).

## Quando a franquia acaba

Hard cap: a API responde `402 quota_exceeded` e o header `X-Credits-Reset` diz quando a franquia renova. Não há cobrança por excedente nem recarga automática. Para continuar antes do reset, o assinante pago compra um pacote avulso, consumido depois da franquia, do mais antigo para o mais novo, com validade de 12 meses:

| Pacote | Preço | Créditos |
| --- | --- | --- |
| Pacote 8 mil | R$ 50 | 8000 |
| Pacote 35 mil | R$ 200 | 35000 |
| Pacote 100 mil | R$ 500 | 100000 |

O Free não compra pacote; precisa assinar. Upgrade é imediato, cobra a diferença proporcional; downgrade vale no próximo ciclo. Pagamento por cartão ou PIX, com NFS-e em toda cobrança.

## Rate limit

O limite de requisições por minuto é **por conta**: todas as chaves da conta somam no mesmo contador. Não há limite de concorrência nem de burst separado no v0. Ao exceder, a API responde `429 rate_limited` com `Retry-After` em segundos; espere esse tempo e repita. Nas respostas `200` de consulta, busca e geração de filtro, `X-RateLimit-Limit` e `X-RateLimit-Remaining` mostram o limite do plano e o que sobra na janela corrente.

Os endpoints sem chave, `GET /v1/status` e `GET /v1/demo`, têm um limite próprio por endereço IP, porque não há conta para contar. Eles servem a páginas públicas e a testes, não a produção.

## Headers das respostas

Declarados no contrato para as respostas `200` de consulta, busca e geração de filtro; `Retry-After` acompanha `429` e `503`.

| Header | Conteúdo |
| --- | --- |
| `X-Request-Id` | Identificador da chamada, o mesmo de `meta.request_id` |
| `X-Credits-Charged` | Créditos desta chamada |
| `X-Credits-Remaining` | Créditos restantes na franquia mais pacotes |
| `X-Credits-Reset` | Quando a franquia renova |
| `X-RateLimit-Limit` | Requisições por minuto do plano |
| `X-RateLimit-Remaining` | Requisições restantes na janela corrente |
| `Retry-After` | Só em `429` e `503`: segundos até tentar de novo |

## Consultar o uso

`GET /v1/usage` custa 0 créditos e devolve a franquia, o consumo do ciclo, os pacotes, o limite de requisições por minuto e a data do reset. O portal mostra os mesmos números, com o débito de cada chamada por `request_id`.

#### curl

```bash
curl "https://api.cnpj.ia.br/v1/usage" \
  -H "Authorization: Bearer $CNPJIA_KEY"
```

Campos da resposta, como o contrato os declara (sem envelope `data`):

| Campo | Tipo |
| --- | --- |
| `plan` | `free` ou `starter` ou `pro` ou `business` ou `scale` |
| `credits_allowance` | integer |
| `credits_used` | integer |
| `credits_remaining` | integer |
| `packs` | array de `sku`, `credits_remaining`, `expires_at` |
| `rpm` | integer |
| `search_enabled` | boolean |
| `cycle_reset_at` | string (date-time) |

## Desempenho

A latência por endpoint passa a ser publicada em [status.cnpj.ia.br](https://status.cnpj.ia.br) quando houver medição em produção. Até lá, nenhuma página das docs afirma número de latência, disponibilidade ou SLA.

## Perguntas frequentes

**Se eu ultrapassar a franquia, vou pagar excedente?**

Não. A franquia tem hard cap: acabou, a API responde `402 quota_exceeded` até o reset ou até você comprar um pacote avulso. Nenhuma cobrança acontece sem uma ação sua.

**Crédito não usado passa para o mês seguinte?**

O da franquia, não: ela renova no primeiro dia do mês-calendário e o saldo anterior zera. Os pacotes avulsos são diferentes: valem doze meses e só são consumidos depois da franquia.

**O rate limit é por chave ou por conta?**

Por conta. Todas as chaves da conta somam no mesmo contador de requisições por minuto. Criar mais chaves organiza o consumo, mas não multiplica o limite; para mais requisições por minuto, o caminho é o plano.

**Erros e 404 consomem crédito?**

Não. Só respostas `200` são cobradas. Um `404 not_found`, um `429 rate_limited` ou um `504 upstream_timeout` deixam o saldo como estava.

**Qual é a latência da API?**

Ainda não publicamos número. A medição por endpoint em produção vai para a status page quando existir; até lá as docs não afirmam latência, disponibilidade nem SLA.