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

# Limites de uso

> O orçamento de requisições de cada chave de API, os cabeçalhos que o informam e como esperar quando você o atinge.

Cada chave de API tem seu próprio orçamento de requisições. O orçamento é contado por chave, não por endereço IP nem por servidor: todas as máquinas que compartilham uma chave compartilham o orçamento dela, e duas chaves nunca compartilham um orçamento.

## O orçamento

| Configuração | Valor atual |
| - | - |
| Requisições por janela | **120** |
| Duração da janela | **60 segundos** |
| Contado por | Chave de API |
| Compartilhado entre | As operações de `/v1` com a mesma chave de API; o MCP usa OAuth separadamente |

A janela é fixa. Ela começa com a primeira requisição que a chave faz depois do fim da janela anterior e é reiniciada 60 segundos depois. Toda requisição que passa pela autenticação conta, qualquer que seja o resultado: um `200`, um `400`, um `404` ou um `429` usam uma unidade cada. As requisições continuam contando enquanto você está acima do limite, mas não aumentam a janela.

Requisições recusadas com `401` `api_keys.invalid` ou `403` `api_keys.scope_missing` são descartadas antes da verificação do orçamento: não contam e não trazem cabeçalhos de limite.

<Note>
  Estes são os valores atuais. Leia o orçamento nos cabeçalhos da resposta em vez de fixá-lo no código, para que sua integração acompanhe qualquer mudança.
</Note>

## Cabeçalhos em toda resposta

Toda resposta a uma requisição autenticada informa o estado do orçamento em duas famílias de cabeçalhos: os amplamente usados `X-RateLimit-*` e os cabeçalhos `RateLimit` do rascunho da IETF.

| Cabeçalho | Exemplo | Significado |
| - | - | - |
| `X-RateLimit-Limit` | `120` | Requisições permitidas por janela. |
| `X-RateLimit-Remaining` | `117` | Requisições restantes na janela atual. `0` quando o orçamento acabou. |
| `X-RateLimit-Reset` | `42` | **Segundos** até a janela reiniciar (não é um timestamp). No mínimo `1`. |
| `RateLimit-Policy` | `120;w=60` | O limite e a duração da janela em segundos. |
| `RateLimit` | `limit=120, remaining=117, reset=42` | O mesmo retrato em um único cabeçalho. |

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
RateLimit-Policy: 120;w=60
RateLimit: limit=120, remaining=117, reset=42
x-request-id: 8d0e5b8a-2f4c-4e1b-9a7d-0c3b5e6f7a81
```

## Quando você passa do limite: `429`

A requisição que ultrapassa o orçamento é recusada com `429 Too Many Requests`, um cabeçalho `Retry-After` com os segundos de espera, os mesmos cabeçalhos de limite e um documento de problema com o código `common.too_many_requests`.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json; charset=utf-8
Retry-After: 18
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
RateLimit-Policy: 120;w=60
RateLimit: limit=120, remaining=0, reset=18
```

```json Accept-Language: pt theme={null}
{
  "type": "https://docs.muveya.com/errors/common.too_many_requests",
  "title": "Muitas solicitações",
  "status": 429,
  "detail": "Muitas solicitações. Tente novamente mais tarde.",
  "instance": "/v1/orders",
  "code": "common.too_many_requests",
  "requestId": "5a1c7e2d-9b3f-4d6a-8e0c-2f4b6d8a0c1e"
}
```

Uma requisição recusada não leu nem alterou nada. É seguro repeti-la depois de esperar os segundos de `Retry-After`.

## Como esperar

<CodeGroup>
  ```javascript JavaScript theme={null}
  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

  async function muveyaGet(url, headers, attempts = 5) {
    for (let attempt = 1; attempt <= attempts; attempt += 1) {
      const response = await fetch(url, { headers });
      if (response.status !== 429) return response;

      const retryAfter = Number(response.headers.get("retry-after") ?? "1");
      await sleep(Math.max(1, retryAfter) * 1000);
    }
    throw new Error("Rate limit: gave up after several attempts");
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def muveya_get(session: requests.Session, url: str, attempts: int = 5, **kwargs):
      for _ in range(attempts):
          response = session.get(url, timeout=30, **kwargs)
          if response.status_code != 429:
              return response
          retry_after = int(response.headers.get("Retry-After", "1"))
          time.sleep(max(1, retry_after))
      raise RuntimeError("Rate limit: gave up after several attempts")
  ```
</CodeGroup>

Bons hábitos:

* **Espere o `Retry-After`** em todo `429`. Tentar antes só soma requisições recusadas à mesma janela.
* **Diminua o ritmo antes de bater no limite.** Quando `X-RateLimit-Remaining` estiver perto de `0`, espere `X-RateLimit-Reset` segundos antes da próxima rajada.
* **Use páginas grandes.** Percorra as listas paginadas com `limit=200` (veja [Paginação](/docs/pt/api-reference/pagination)).
* **Guarde em cache o que muda pouco.** Unidades, depósitos e categorias não precisam ser lidos a cada execução.
* **Consulte as exportações com calma.** Uma consulta a cada poucos segundos basta enquanto uma exportação está sendo gerada (veja [Exportações do resumo gerencial](/docs/pt/api-reference/exports)).
* **Não rode processos sobrepostos** com a mesma chave. Agende um depois do outro.
* **Use uma chave por integração.** Cada chave tem seu próprio orçamento, então um processo pesado não deixa outro sem requisições.

Se sua integração precisar de um orçamento maior, escreva para [team@muveya.com](mailto:team@muveya.com) informando o volume de requisições esperado.

## Páginas relacionadas

* [Erros](/docs/pt/api-reference/errors)
* [Webhooks](/docs/pt/api-reference/webhooks): consultas periódicas dentro do orçamento
* [Escopos](/docs/pt/api-reference/scopes)


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