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

# Limites de Requisição

> Quantas requisições sua integração pode enviar e como reagir ao limite.

## Visão geral

A API Cakto aplica limites de taxa para proteger a plataforma. Ao ultrapassar um limite, a resposta é `429 Too Many Requests`.

## Limites por endpoint

| Endpoint | Limite | Contado por |
| - | - | - |
| `POST /public_api/token/` | 20 por minuto | Endereço IP de origem |
| `POST /public_api/token/` | 200 por hora | Endereço IP de origem |
| `POST /public_api/payments/` | 60 por minuto | Endereço IP de origem |
| `POST /public_api/payments/` | 120 por minuto | Token de acesso (chave de API) |
| `POST /public_api/card-tokens/` | 20 por minuto | Usuário autenticado |
| `POST /public_api/withdrawals/` | **2 por hora** | Token de acesso (chave de API) |
| Demais endpoints autenticados | 5.000 por hora | Usuário autenticado |
| Requisições não autenticadas | 200 por hora | Endereço IP de origem |

> [!WARNING]
>
> **Os dois limites de emissão de token valem ao mesmo tempo, e são contados por IP** — não por credencial. No momento da emissão a credencial ainda não foi validada, então o IP é o único identificador disponível; integrações que saem pelo mesmo endereço dividem esse teto.
>
> Na prática ele quase nunca é atingido: com validade de 10 horas, quem guarda o token não chega perto de 20 emissões por minuto. Encostar nesse limite costuma significar que a integração está pedindo um token novo a cada chamada — veja [Autenticação](https://docs.cakto.com.br/authentication.md).

> [!WARNING]
>
> Os dois limites de **Criar Cobrança** valem ao mesmo tempo. Uma integração que concentra o tráfego num único IP atinge o teto de 60/min mesmo usando vários tokens.

> [!WARNING]
>
> **Solicitar Saque tem o limite mais baixo da API — 2 por hora — e é intencional.** Não é capacidade: é contenção. Uma chave de API vazada com `withdrawals_write` consegue, no pior caso, dois saques por hora até você revogá-la, em vez de esvaziar a conta. Agrupe os saques em vez de pedir em valores pequenos.

> [!NOTE]
>
> Estes são os valores padrão. Se sua operação tem volume acima disso, fale com o [suporte](mailto:infoprodutores@cakto.com.br) antes de escalar.

## Resposta ao exceder

```json theme={null}
{
  "detail": "Request was throttled. Expected available in 42 seconds."
}
```

A resposta inclui o header `Retry-After` com o número de segundos a aguardar.

> [!NOTE]
>
> **`POST /public_api/token/` responde em formato OAuth**, igual aos demais erros daquele endpoint:
>
> ```json theme={null}
> {
>   "error": "slow_down",
>   "error_description": "Too many token requests. Reuse the access token until it expires."
> }
> ```
>
> O header `Retry-After` acompanha os dois formatos.

## Como reagir

> [accordion] Respeite o Retry-After
>
> Ao receber `429`, aguarde o tempo indicado no header `Retry-After` antes de tentar de novo. Reenviar imediatamente só consome o limite outra vez.

> [accordion] Use backoff exponencial
>
> Se o header não estiver disponível, aumente o intervalo a cada tentativa (por exemplo 1s, 2s, 4s, 8s) em vez de repetir em intervalo fixo.

> [accordion] Reutilize a chave de idempotência
>
> Ao repetir uma cobrança que tomou `429`, mantenha o **mesmo** `X-Idempotency-Key`. Assim, se a requisição original tiver sido processada, você recebe a resposta original em vez de uma cobrança duplicada. Veja [Idempotência](https://docs.cakto.com.br/conceitos/idempotencia.md).

> [accordion] Distribua o processamento em lote
>
> Ao processar filas grandes, espace as requisições ao longo do minuto em vez de dispará-las todas de uma vez.

## Próximos passos

> [card] [Idempotência](https://docs.cakto.com.br/conceitos/idempotencia.md)
>
> Repita requisições sem duplicar cobranças

> [card] [Erros](https://docs.cakto.com.br/conceitos/erros.md)
>
> Formato das respostas de erro da API


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