# Limites de pedidos

Cada chave de API tem um orçamento de 100 pedidos por segundo. Leia os cabeçalhos RateLimit-*, trate a resposta 429 e repita só depois de Retry-After.


## Como o limite funciona

O limite aplica-se a cada chave de API, não à conta: duas chaves da mesma empresa têm orçamentos independentes. Cada chave pode fazer 100 pedidos por segundo, contados em janelas de um segundo. Quando o servidor guarda as contagens na base de dados, todas as réplicas partilham a mesma janela; se essa contagem partilhada falhar, cada processo aplica o mesmo orçamento localmente.

O limite vale em todas as áreas da API (Business, Consumer, Platform, Public e Connector) sempre que o pedido apresenta uma chave. Pedidos feitos com a sessão do painel ou com um token OAuth não passam por este limitador e não recebem os cabeçalhos abaixo. Ao rodar uma chave, a nova recebe um ID novo e, com ele, um orçamento próprio.

## Cabeçalhos em cada resposta

Todas as respostas a um pedido feito com chave trazem três cabeçalhos:

| Cabeçalho | Significado |
| :--- | :--- |
| `RateLimit-Limit` | Pedidos permitidos por janela (`100`). |
| `RateLimit-Remaining` | Pedidos que ainda restam na janela actual. |
| `RateLimit-Reset` | Segundos, arredondados para cima, até a janela recomeçar. |

Quando o orçamento se esgota, a resposta é `429 Too Many Requests` e inclui também `Retry-After`, com o mesmo valor de `RateLimit-Reset`.

```bash
curl -sS -i "$BUSINESS_API/customers?limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
Request-Id: req_7f3a9c21d04b4e6f8a12b5c9e0d7f364

{
  "type": "about:blank",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "This API key (sk_rtest_C3J2) exceeded its request budget; retry after the RateLimit-Reset seconds.",
  "instance": "$BUSINESS_API/customers",
  "code": "RATE_LIMITED",
  "error_code": "request.rate_limited",
  "request_id": "req_7f3a9c21d04b4e6f8a12b5c9e0d7f364"
}
```

O `detail` identifica a chave pelo prefixo, nunca pelo segredo. Se o operador tiver configurado o site de documentação, `type` aponta para a âncora `request.rate_limited` da página de erros; caso contrário vale `about:blank`. Trate o erro pelo `error_code` e não pelo texto.

## Repetir com segurança

1. Leia `RateLimit-Remaining` em cada resposta e abrande quando se aproximar de zero.
2. Perante um `429`, aguarde os segundos de `Retry-After` e só depois repita o mesmo pedido.
3. Em pedidos `POST` que criam recursos, envie sempre o mesmo `Idempotency-Key` na repetição, para que um pedido recusado e repetido não crie dois registos.

```javascript
async function comLimite(url, options, tentativas = 3) {
  for (let i = 0; i < tentativas; i++) {
    const res = await fetch(url, options);
    if (res.status === 429) {
      const espera = Number(res.headers.get("Retry-After") || "1");
      await new Promise((r) => setTimeout(r, espera * 1000));
      continue;
    }
    return res;
  }
  throw new Error("orçamento da chave esgotado");
}
```

A CLI `gotactl` já faz isto: perante um `429` espera `Retry-After` (um segundo, se o cabeçalho faltar) e tenta mais duas vezes; se a terceira tentativa também for recusada, termina com o código de saída `5`.

## Outros limites

Alguns pontos sem chave, como os pedidos públicos e o início de sessão, têm orçamentos próprios e respondem igualmente `429` com `Retry-After`, mas sem os cabeçalhos `RateLimit-*`. Os pedidos de uma chave recusados pelo limitador continuam a aparecer em **Programadores** > **Registos**, com o estado `429`.

## Próximos passos

- [Como o Idempotency-Key evita registos duplicados](/docs/getting-started/idempotency)
- [Formato dos erros e lista de códigos](/docs/getting-started/errors)
- [Rodar uma chave sem interromper a integração](/docs/getting-started/api-keys)

