> ## 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

# Rate Limiting

As APIs Zipdin implementam rate limiting para garantir estabilidade e disponibilidade para todos os clientes.

## 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"
  }
}
```

## Boas Práticas

<Steps>
  <Step title="Respeite o Retry-After">
    Quando receber 429, 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>