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

# Rate Limiting

> Limites de requisições e boas práticas para alto volume

Para manter a plataforma estável e justa para todos os integradores, as APIs Zipdin limitam quantas
requisições cada `client_id` pode fazer por minuto. Ao ultrapassar esse teto, a API responde `429` em
vez de processar a chamada — por isso vale desenhar sua integração para respeitar os limites desde o
início, e não apenas reagir quando o erro aparece.

Esta página descreve os limites de cada ambiente, os headers que informam seu consumo em tempo real, o
que esperar quando o limite é excedido e as boas práticas para operar em alto volume sem esbarrar no teto.

## Limites por Ambiente

| Ambiente    |    Limite   |     Janela     |
| ----------- | :---------: | :------------: |
| Homologação | 200 req/min | Por client\_id |
| Produção    | 500 req/min | Por client\_id |

## Headers de Resposta

Toda resposta inclui headers de rate limit:

```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1691345400
```

| Header                  | Descrição                         |
| ----------------------- | --------------------------------- |
| `X-RateLimit-Limit`     | Limite total na janela            |
| `X-RateLimit-Remaining` | Requisições restantes             |
| `X-RateLimit-Reset`     | Unix timestamp de reset da janela |

## Quando o Limite é Excedido

```json theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 45

{
  "error": "RATE_LIMITED",
  "message": "Limite excedido. Tente novamente em 45 segundos.",
  "details": {
    "retry_after": 45,
    "limit": 500,
    "window": "1m"
  }
}
```

## Throttling da DATAPREV no E-Consignado

O rate limit acima é da borda da API Zipdin. No **E-Consignado**, há um segundo ponto de limitação
fora do controle da Zipdin: a própria **DATAPREV** pode responder `429` para o Dataprev Controller
durante a obtenção do token de autorização, em picos de volume.

Quando isso acontece, você **não recebe um `429`** — o Dataprev Controller repassa a limitação da
DATAPREV como **`502 Bad Gateway`** com o erro `token_acquisition_failed`:

```json theme={null}
HTTP/1.1 502 Bad Gateway

{
  "error": "token_acquisition_failed",
  "message": "Falha ao obter tokenAutorizacao: Request failed with status code 429"
}
```

<Warning>
  Não há header `Retry-After` nesse caso. Trate `502 token_acquisition_failed` como uma falha
  transitória: aguarde alguns segundos e tente novamente, com intervalo crescente entre as tentativas.
  Veja [Tratamento de Erros](/docs/conceitos/error-handling).
</Warning>

## Boas Práticas

<Steps>
  <Step title="Respeite o Retry-After">
    Quando receber 429 da API Zipdin, aguarde o tempo indicado no header `Retry-After`.
  </Step>

  <Step title="Monitore os headers">
    Acompanhe `X-RateLimit-Remaining` para evitar atingir o limite.
  </Step>

  <Step title="Use cache">
    Cache respostas de consultas frequentes (ex: dados de conveniada).
  </Step>

  <Step title="Batch quando possível">
    Agrupe operações em lote em vez de chamadas individuais.
  </Step>
</Steps>

<Note>
  Para necessidades acima de 500 req/min em produção, entre em contato com
  o time de integrações para discutir um plano dedicado.
</Note>