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

# Limites de requisição

> Quantas requisições a sua empresa pode fazer por minuto, como acompanhar o limite pelos cabeçalhos e como tratar o 429

export const v_0 = "v2"

Para manter a API estável para todos os clientes, a Salvy limita quantas requisições cada empresa pode fazer por minuto. A sua integração consegue acompanhar esse limite pelos cabeçalhos de cada resposta e se ajustar antes de ser bloqueada.

## Qual é o limite

| O que é contado | Limite padrão |
| - | - |
| Requisições por empresa | **300 por minuto** |

* O limite é **por empresa**, não por chave de API: todas as chaves da mesma empresa dividem a mesma janela. Criar mais chaves não aumenta o limite.
* Chaves de organização contam na janela da **organização**, separada da janela de cada empresa.
* A janela é fixa de um minuto: ela começa na primeira requisição e zera quando o minuto termina.

<Tip>
  Se a sua integração precisa de mais do que isso, fale com o seu contato na
  Salvy. O limite pode ser ajustado por empresa.
</Tip>

## Como acompanhar o limite

As respostas autenticadas trazem dois cabeçalhos:

| Cabeçalho | O que informa | Exemplo |
| - | - | - |
| `RateLimit-Limit` | Quantas requisições a janela permite | `300` |
| `RateLimit-Remaining` | Quantas ainda cabem na janela atual | `287` |

Quando `RateLimit-Remaining` chegar perto de zero, espace as próximas chamadas em vez de esperar pelo bloqueio.

Os cabeçalhos não aparecem em respostas `401` e `403`, porque a autenticação é avaliada antes. Trate a ausência de `RateLimit-Remaining` como "sem informação", não como limite esgotado.

## Quando o limite é atingido

A requisição que passa do limite recebe `429 Too Many Requests` com o código `too-many-attempts`. O cabeçalho `Retry-After` diz, em segundos, quanto falta para a janela zerar:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 18
RateLimit-Limit: 300
RateLimit-Remaining: 0
```

Nada é executado numa requisição recusada. É seguro repeti-la depois do tempo indicado, inclusive quando for uma criação ou alteração.

### Outro 429: a proteção de borda

Além do limite por empresa, a Salvy tem uma proteção de borda contra picos vindos de um mesmo IP. Ela responde `429` com o código `too-many-requests` e **sem** `Retry-After`. Se receber esse código, aguarde alguns segundos e tente de novo com espera crescente.

## Como tratar o 429

```js theme={null}
async function callSalvy(url, init, attempt = 0) {
  const response = await fetch(url, {
    ...init,
    headers: {
      ...init?.headers,
      Authorization: `Bearer ${process.env.SALVY_API_KEY}`,
    },
  });

  if (response.status !== 429 || attempt >= 5) {
    return response;
  }

  // Sem Retry-After (proteção de borda), espera crescente: 1s, 2s, 4s...
  const retryAfter = Number(response.headers.get('Retry-After'));
  const waitSeconds = retryAfter > 0 ? retryAfter : 2 ** attempt;

  await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));

  return callSalvy(url, init, attempt + 1);
}
```

<Warning>
  Não repita a requisição imediatamente em laço. Enquanto a janela não zerar,
  toda nova tentativa volta com `429`.
</Warning>

## Boas práticas

* **Sincronizações em lote**: distribua as chamadas ao longo do tempo em vez de disparar tudo de uma vez.
* **Várias integrações na mesma empresa**: lembre que elas dividem o mesmo limite. Um job pesado pode esgotar a janela de outra integração.
* **Agentes de IA e scripts**: limite a concorrência. Um laço sem pausa atinge 300 requisições em poucos segundos.
* **Teste no sandbox**: chaves `salvy_test_` seguem o mesmo limite. Veja <a href={"/api-reference/" + v_0 + "/environments"}>Ambientes</a>.

## Corpo da resposta 429

O corpo segue o formato de erro da v2. O tempo de espera também vem no corpo, para clientes que não leem cabeçalhos:

```json theme={null}
{
  "code": "too-many-attempts",
  "message": "Muitas requisições em pouco tempo. Aguarde um instante e tente de novo.",
  "publicDetails": {
    "friendlyMessage": "Muitas requisições em pouco tempo. Aguarde um instante e tente de novo.",
    "retryAfterSeconds": 18
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.