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

# Rate limit

> Limites de requisições da API da Spedy e como lidar com o erro 429.

Para manter a API estável para todos os clientes, cada chave de API está
sujeita a um limite de requisições.

| Limite      | Valor          |
| ----------- | -------------- |
| Por minuto  | 60 requisições |
| Por segundo | 5 requisições  |

Ao exceder o limite, a API responde `429 Too Many Requests`.

## Headers de resposta

Toda resposta traz headers que indicam seu consumo atual do limite:

| Header                   | Descrição                                    |
| ------------------------ | -------------------------------------------- |
| `x-rate-limit-limit`     | Limite total configurado para a janela atual |
| `x-rate-limit-remaining` | Requisições restantes na janela atual        |
| `x-rate-limit-reset`     | Quando a janela atual é renovada             |

Use esses headers para monitorar seu consumo e evitar bater no limite, em vez
de descobrir isso só quando receber um `429`.

## Lidando com o 429: retry com backoff

Quando receber `429`, espere antes de tentar novamente — e aumente o tempo de
espera a cada nova tentativa (backoff exponencial), em vez de tentar de novo
imediatamente.

```typescript theme={null}
// Retry com backoff exponencial ao receber 429
async function fetchComRetry(
  url: string,
  init: RequestInit,
  maxTentativas = 5,
): Promise<Response> {
  let atraso = 1000; // 1s

  for (let tentativa = 1; tentativa <= maxTentativas; tentativa++) {
    const resposta = await fetch(url, init);

    // Sucesso (ou último erro) — devolve sem esperar
    if (resposta.status !== 429 || tentativa === maxTentativas) {
      return resposta;
    }

    console.warn(`Rate limit atingido, tentando novamente em ${atraso}ms...`);
    await new Promise((r) => setTimeout(r, atraso));
    atraso *= 2; // backoff exponencial
  }

  throw new Error("Número máximo de tentativas excedido");
}

// Uso
const resposta = await fetchComRetry(
  "https://sandbox-api.spedy.com.br/v1/companies/{id}",
  { headers: { "X-Api-Key": "sua-chave-de-api" } },
);
const dados = await resposta.json();
```

<Tip>
  Se sua integração faz emissões em lote, distribua as chamadas ao longo do
  tempo (ex.: uma fila com controle de taxa) em vez de disparar tudo de uma
  vez. Isso evita 429s e reduz a necessidade de retries.
</Tip>

<Note>
  Precisa de um limite maior para o seu volume de emissão? Fale com o time da
  Spedy.
</Note>