Limites de uso

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.

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.

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/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/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

Accept-Language: pt

{
  "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

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");
}

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")

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).
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).
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 informando o volume de requisições esperado.

Páginas relacionadas

Erros
Webhooks: consultas periódicas dentro do orçamento
Escopos

Visão geral

Endpoints

Limites de uso

O orçamento

Cabeçalhos em toda resposta

Quando você passa do limite: `429`

Como esperar

Páginas relacionadas

​O orçamento

​Cabeçalhos em toda resposta

​Quando você passa do limite: 429

​Como esperar

​Páginas relacionadas

O orçamento

Cabeçalhos em toda resposta

Quando você passa do limite: `429`

Como esperar

Páginas relacionadas