Limites de pedidos

A API do GetQR está em versão beta e só está disponível para alguns espaços de trabalho. Os detalhes podem mudar antes do lançamento geral.

A API do GetQR limita o número de pedidos que cada chave de API pode enviar, para que uma única integração não torne a API mais lenta para todos.

Limites

Limite	Valor
Pedidos por chave de API	600 por minuto

O limite é contado numa janela deslizante de um minuto e aplica-se a todos os endpoints em conjunto. A verificação de estado não precisa de chave e não conta.

Cabeçalhos de limite de pedidos

As respostas a pedidos com uma chave de API válida incluem estes cabeçalhos, incluindo as respostas de erro:

Cabeçalho	Descrição
`X-RateLimit-Limit`	Número máximo de pedidos por janela.
`X-RateLimit-Remaining`	Pedidos que restam na janela atual.
`X-RateLimit-Reset`	Quando a janela reinicia, como carimbo de data/hora Unix em milissegundos.
`Retry-After`	Segundos até a janela reiniciar, arredondados para cima. Aguarde esse tempo antes de tentar novamente.

Quando ultrapassa o limite

Acima do limite, a API responde 429 com o código rate_limit_exceeded e os mesmos cabeçalhos:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792764060000
Retry-After: 37

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests.",
    "doc_url": "https://getqr.com/account/api-docs#error-rate_limit_exceeded"
  }
}

Aguarde até ao momento do reinício antes de enviar mais pedidos. Adicione uma variação aleatória (jitter) para que vários processos não repitam ao mesmo tempo, e aplique uma espera exponencial nos erros 5xx:

async function getqrFetch(url, options = {}, maxRetries = 5) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.GETQR_API_KEY}`,
        ...options.headers,
      },
    });

    const retryable = res.status === 429 || res.status >= 500;
    if (!retryable || attempt >= maxRetries) return res;

    // On 429, wait for Retry-After (seconds). Otherwise back off: 1s, 2s, 4s…
    const retryAfter = Number(res.headers.get("Retry-After"));
    const wait =
      res.status === 429 && retryAfter > 0
        ? retryAfter * 1000
        : 1000 * 2 ** attempt;
    const jitter = Math.random() * 250;

    await new Promise((r) => setTimeout(r, wait + jitter));
  }
}

Só repita POST /api/v1/qrs com um cabeçalho Idempotency-Key. Assim, uma repetição nunca cria um segundo código QR. Consulte Idempotência.

Manter-se abaixo do limite

Acompanhe X-RateLimit-Remaining e abrande antes de chegar a 0.
Use a criação de QR em massa em vez de um pedido por código QR.
Obtenha até 100 resultados por página com pageSize=100. Consulte Paginação.
Coloque as imagens de QR em cache: as transferências devolvem um ETag, pelo que pode enviar If-None-Match e receber 304 Not Modified quando nada mudou.

API

Limites

Cabeçalhos de limite de pedidos

Quando ultrapassa o limite

Manter-se abaixo do limite

Próximos passos

Erros

Códigos QR

​Limites

​Cabeçalhos de limite de pedidos

​Quando ultrapassa o limite

​Manter-se abaixo do limite

​Próximos passos

Erros

Códigos QR

Limites

Cabeçalhos de limite de pedidos

Quando ultrapassa o limite

Manter-se abaixo do limite

Próximos passos