Limites de taxa

O UnifAPI aplica um único limite de requisições: 60 requisições a cada 60 segundos, por chave de API. Ele vale para a chave, não para o workspace nem para o endpoint — duas chaves do mesmo workspace não disputam o mesmo saldo, e nenhuma operação tem um limite próprio mais rígido.

Headers

Toda resposta — 2xx, 4xx ou 5xx — carrega a cota que se aplica a ela, então você nunca precisa de uma requisição de sondagem para saber onde está.

Uma resposta que nunca resolveu uma chave de API — um 401, por exemplo — informa a política padrão com o saldo cheio. Ela descreve a cota que você encontrará depois de autenticar, não o uso já consumido.

Clientes de navegador conseguem ler todos eles: aparecem em Access-Control-Expose-Headers nas respostas cross-origin.

HTTP/1.1 200 OK
RateLimit-Policy: "api-key";q=60;w=60
RateLimit: "api-key";r=57;t=60
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 60

A janela

A janela é ancorada na requisição mais recente da chave: o contador zera quando uma janela inteira passa sem chamadas dessa chave. Não há folga para burst, então projete para a taxa em regime estável, e não para um saldo acumulado.

Lidando com 429

async function call(url: string, init: RequestInit, attempt = 0): Promise<Response> {
  const res = await fetch(url, init);
  if (res.status !== 429 || attempt >= 5) return res;

  const wait = Number(res.headers.get("Retry-After") ?? res.headers.get("RateLimit-Reset") ?? 1);
  await new Promise((r) => setTimeout(r, wait * 1000));
  return call(url, init, attempt + 1);
}

Duas regras para o dia a dia:

1. Regule o ritmo antes de ser limitado. Leia RateLimit-Remaining em cada resposta e desacelere conforme ele se aproxima de 0. Esperar um 429 para começar a regular desperdiça uma ida e volta em todos os workers ao mesmo tempo.
2. Respeite o Retry-After. É a espera que o limitador realmente precisa; chutar costuma piorar. Se ele não vier, use o RateLimit-Reset. Aumentar a concorrência depois de um 429 nunca ajuda — o limite é por chave.

Pedindo mais

Os limites são definidos por chave, então um limite maior é uma mudança de configuração, não um upgrade de plano. Escreva para support@unifapi.com com o ID do seu workspace, a Skill ou operação que você executa e uma estimativa aproximada de QPS.