# Limites de requisição

URL: https://staging.pagpolar.com/docs/guias/fundamentos/limites-de-requisicao

> Saiba quantas chamadas por minuto sua credencial pode fazer, como os limites se somam e o que fazer no 429 e no 503.

## Limite geral da credencial

Cada credencial pode fazer um número máximo de requisições por minuto. Não existe limite separado por rota nem por grupo de rotas: **toda** chamada conta na mesma contagem da credencial. Uma venda PIX, uma listagem e uma troca de cartão consomem exatamente o mesmo 1 de 120.

* O padrão é **120 requisições por minuto**.
* O valor da sua credencial aparece em `rate_limit_per_minute`, na resposta de [`GET /me`](/docs/referencia/autenticacao/get-current-credential).
* Você não altera o limite. Veja [Como aumentar o limite](#aumentar-limite).

A contagem usa uma janela móvel: a API conta as requisições feitas nos **últimos 60 segundos**, a cada nova requisição.

O que conta e o que fica de fora:

* `POST /auth/token` **não conta** no limite.
* Requisições recusadas com `429` **também contam**. Repetir sem esperar mantém você bloqueado.
* Requisições recusadas na autenticação (`401`) ou por IP não autorizado (`403`) não contam.

## Headers de limite

As respostas trazem estes headers:

| Header                  | O que significa                                            |
| ----------------------- | ---------------------------------------------------------- |
| `X-RateLimit-Limit`     | O `rate_limit_per_minute` da credencial.                   |
| `X-RateLimit-Remaining` | Quantas requisições ainda cabem na janela de 60 segundos.  |
| `X-RateLimit-Reset`     | Tamanho da janela, em segundos. Hoje é sempre `60`.        |
| `Retry-After`           | Só no `429`. Quantos segundos esperar. Hoje é sempre `60`. |

## Resposta 429

Quando o limite estoura, a resposta é:

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Limite de requisições excedido. Aguarde e tente novamente.",
    "request_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
  }
}
```

O que fazer:

1. Pare de enviar requisições para essa credencial.
2. Espere os segundos de `Retry-After`.
3. Repita. Numa rota de cobrança, repita com a **mesma** `Idempotency-Key`.

Para não chegar no limite, veja as dicas em [Como aumentar o limite](#aumentar-limite).

## Como aumentar o limite

Quem aumenta o `rate_limit_per_minute` da credencial é o suporte.

Antes de pedir, reduza as chamadas:

* Use `per_page=100` nas listagens, para buscar mais itens por chamada. Veja [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros).
* Receba os webhooks em vez de consultar a API em loop para saber se algo mudou. Veja [Webhooks](/docs/webhooks).

1. **Veja o limite atual**

   Chame [`GET /me`](/docs/referencia/autenticacao/get-current-credential), como em [Envie o token em `Authorization`](/docs/guias/fundamentos/autenticacao#enviar-o-token), e anote `rate_limit_per_minute` e `credential_id`: o suporte precisa dele.

2. **Fale com o suporte**

   Informe:

       | O quê                                | Exemplo                                                                 |
       | ------------------------------------ | ----------------------------------------------------------------------- |
       | O `credential_id` da credencial      | `7c9e6679-7425-40de-944b-e07fc1f90ae7`                                  |
       | O limite por minuto que você precisa | `300`                                                                   |
       | O uso esperado                       | Picos de venda num lançamento, ou sincronização do catálogo de ofertas. |

       O ajuste vale para a credencial informada. Se você usa mais de uma credencial, informe cada `credential_id`.

3. **Confira o novo limite**

   Depois do ajuste, chame `GET /me` de novo e confira `rate_limit_per_minute`. O header `X-RateLimit-Limit` das respostas também mostra o valor. A API guarda os dados da credencial em cache por até 1 minuto: se ainda aparecer o valor antigo, espere 1 minuto e confira de novo.

       Não é preciso gerar outra chave nem outro token: o token que você já usa continua valendo.

## Resposta 503

Só as rotas que movimentam dinheiro respondem `503`: as três de cobrança, a criação de assinatura, o reembolso, a troca de plano e a troca de cartão. Isso acontece quando o controle de limite fica fora do ar:

```json
{
  "error": {
    "code": "service_unavailable",
    "message": "Serviço temporariamente indisponível. Tente novamente em instantes.",
    "request_id": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f60"
  }
}
```

A requisição **não** foi processada. Espere alguns segundos e repita. Nas rotas com `Idempotency-Key`, use a mesma chave. A troca de cartão não usa `Idempotency-Key`.

Nas outras rotas, se o controle de limite ficar fora do ar, a requisição segue normalmente.

## Próximos passos

- [Idempotência](/docs/guias/fundamentos/idempotencia) — Repita uma cobrança sem cobrar duas vezes.
- [Paginação e filtros](/docs/guias/fundamentos/paginacao-e-filtros) — Busque mais dados com menos chamadas.