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

# Limites de requisição

> Quantas chamadas cada chave de API faz por minuto, o que acontece ao passar do limite e como integrar sem esbarrar nele.

A Chargefy limita o ritmo de chamadas de cada chave de API. O limite protege o
checkout e a API de todas as organizações quando uma integração entra em laço
ou faz uma varredura grande de uma vez. Consultas e criações têm cotas
separadas, e uma cota curta de 10 segundos segura rajadas.

## Limites por chave

| Cota | Chave de organização | Chave de plataforma |
| - | - | - |
| Consultas (`GET`) por minuto | 120 | 1.800 |
| Criações e alterações (`POST`, `PATCH`, `DELETE`) por minuto | 120 | 720 |
| Qualquer chamada em 10 segundos | 40 | 450 |

* A contagem é por chave de API. Duas chaves da mesma organização têm cotas
  independentes.
* No **Chargefy for Platforms**, chamadas da chave de plataforma com o header
  `Organization` usam a cota de plataforma, somando todas as organizações
  conectadas.
* Não contam: as páginas hospedadas (checkout, fatura, portal do cliente e
  ativação), as chamadas do [Chargefy.js](/api/chargefy-js) no navegador do
  comprador e o MCP, que tem [limites próprios](/mcp/limits).
* 120 criações por minuto equivalem a 7.200 pagamentos por hora numa única
  chave.

## Ao passar do limite

A chamada volta `429` com o tipo `rate_limit_error` e o header `Retry-After`,
em segundos. Ela não chega a ser processada: nada é criado nem alterado.

```json theme={"theme":"css-variables"}
{
  "error": {
    "code": "rate_limit_exceeded",
    "doc_url": "https://docs.chargefy.io/api-reference/rate-limits",
    "message": "Too many read requests for this API key. Retry after 60 seconds.",
    "request_log_url": "https://dashboard.chargefy.io/request-logs/req_9xK2mQ7vT4nB8wLp",
    "type": "rate_limit_error"
  }
}
```

A mensagem diz qual cota acabou: `read requests` (consultas), `write requests`
(criações e alterações) ou `requests in a short burst` (rajada de 10
segundos). O primeiro `429` de cada chave em cada minuto aparece nos
[registros de requisições](/api-reference/requests/list).

## Como tratar o 429

* Espere o tempo de `Retry-After` antes de repetir. Somando um pequeno atraso
  aleatório, chamadas paradas ao mesmo tempo não voltam juntas.
* Ao repetir uma criação ou alteração, envie o mesmo
  [`Idempotency-Key`](/api-reference/idempotency): a operação roda uma única
  vez.
* Em lote, distribua no tempo. Importar 500 cupons leva cerca de 5 minutos a
  120 por minuto, em vez de esbarrar no limite no primeiro minuto.

## Aguarde o Pix pelo webhook

Para saber quando um Pix foi pago, cadastre um
[endpoint de webhook](/integrate/webhooks/delivery) e processe
`payment.intent.succeeded`. O evento sai assim que o pagamento é confirmado,
sem nenhuma consulta da sua integração.

Consultar o pagamento em laço gasta a cota de consultas sem trazer a
informação antes. Uma tela que pergunta "já foi pago?" a cada 2 segundos faz
30 consultas por minuto por comprador; com quatro compradores pagando ao mesmo
tempo, a chave chega ao limite. Se não houver como receber webhook, consulte
no máximo a cada 10 segundos, aumente o intervalo a cada tentativa e pare no
`expires_at` do código Pix. Veja o fluxo completo em
[Criar um pagamento](/payments/create-payment).

## Sincronize por período, não item por item

Para trazer para o seu sistema o que mudou num período, use a listagem com
filtro de data e `limit=100`, e não uma consulta por ID. Sincronizar 300
transações do dia leva 3 chamadas assim, contra 300 consultas individuais.

```bash theme={"theme":"css-variables"}
curl -G "https://api.chargefy.io/v1/transactions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  --data-urlencode "created_at[gte]=2026-10-06T00:00:00Z" \
  -d limit=100
```

Para as páginas seguintes, envie o ID do último item em `starting_after`.
Veja [Paginação](/api-reference/pagination).


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