> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/prioridades-e-rate-limit.md).

# Prioridades e Rate Limit

A API GTFgts aplica **rate limit por originator**. Acima da cota normal, a operação ainda pode ser **admitida** com prioridade rebaixada (`202`); acima do limite, a requisição é **rejeitada** com `429` e o header `Retry-After`. O cliente nunca envia um campo de prioridade — a prioridade resultante é definida pela própria API.

***

## Prioridades: `NORMAL` vs `DEFERRED`

| Prioridade | Quando se aplica                                                                              | Efeito                                                     |
| ---------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `NORMAL`   | Operações individuais dentro da cota normal                                                   | Processadas com prioridade de tempo real                   |
| `DEFERRED` | Consulta em **lote** (`/batch/balance-queries`) **ou** operação admitida acima da cota normal | Menor prioridade — não compete com o tráfego em tempo real |

{% hint style="info" %}
A rota `/batch/balance-queries` é **sempre** `DEFERRED` — a própria rota é o sinal de prioridade; o cliente não envia um campo de prioridade. Cada chamada carrega **um único CPF** (o mesmo corpo da rota normal): "lote" indica a **prioridade**, não um envio em massa. A rota de lote **consome a mesma cota por originator** da rota normal — **não há uma cota separada de lote**. Ver [Operações FGTS](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/operacoes-fgts.md).
{% endhint %}

***

## Comportamento do rate limit

```mermaid
flowchart TD
    A[Requisição do originator] --> B{Dentro da cota normal?}
    B -- Sim --> C[202 Accepted - prioridade NORMAL]
    B -- Não --> D{Dentro do limite?}
    D -- Sim - acima da cota normal --> E[202 Accepted - prioridade DEFERRED]
    D -- Não - limite excedido --> F[429 Too Many Requests - Retry-After]
```

| Faixa                     | Comportamento                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------- |
| **Dentro da cota normal** | A operação é admitida com prioridade `NORMAL` (`202`).                                 |
| **Acima da cota normal**  | A operação ainda é **admitida** (`202`), mas com prioridade rebaixada para `DEFERRED`. |
| **Acima do limite**       | A requisição é **rejeitada** com `429` e o header `Retry-After`.                       |

{% hint style="info" %}
A cota é **por originator** e **varia conforme o horário (horário de Brasília)**: em **horário comercial** vale uma cota menor; **à noite e nos fins de semana**, a cota é maior. A transição é automática — você não configura nada e o contrato de resposta não muda (`202` normal, `202` `DEFERRED`, ou `429`). As operações `DEFERRED` (incluindo a rota de lote) são processadas **atrás** do tráfego em tempo real, conforme a capacidade disponível. Em horário comercial, sob carga, a chance de `DEFERRED`/`429` é maior.
{% endhint %}

***

## A resposta `429`

Ao exceder o limite, a API responde `429` com um `ProblemDetail` (`application/problem+json`) e o `errorCode: INGRESS_RATE_LIMIT_EXCEEDED`.

### Headers

| Header                  | Descrição                                          |
| ----------------------- | -------------------------------------------------- |
| `Retry-After`           | Segundos até a próxima janela disponível.          |
| `X-RateLimit-Limit`     | Limite de requisições na janela de medição.        |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual.             |
| `X-RateLimit-Reset`     | Epoch (ms) em que a janela de rate limit reinicia. |

### Corpo

```json
{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 1 second.",
  "errorCode": "INGRESS_RATE_LIMIT_EXCEEDED",
  "timestamp": "2026-06-14T12:00:00Z"
}
```

***

## Como tratar o `429`

1. **Respeite o `Retry-After`.** Aguarde o número de segundos indicado antes de reenviar — não tente imediatamente.
2. **Use os headers `X-RateLimit-*`** para antecipar a saturação: quando `X-RateLimit-Remaining` se aproxima de zero, reduza o ritmo de envio.
3. **Distribua o volume.** Para grandes volumes de consultas de saldo, prefira a rota de **lote** (`DEFERRED`), que não compete com o tráfego em tempo real e reduz a chance de exceder o limite.
4. **Aplique back-off** se receber `429` repetidamente, aumentando progressivamente o intervalo entre tentativas.

{% hint style="warning" %}
O `429` é um erro de **borda** (`ProblemDetail`), não um erro de operação. Ele indica que a requisição **não foi admitida** — nenhum `requestId` é gerado. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md#rate-limit-exceeded).
{% endhint %}

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
