Manipulador de Limite de Taxa da API

Visão Geral

Uma habilidade para implementar limite de taxa de nível de produção, backoff exponencial e estratégias de retentativa ao integrar com APIs externas. Evita falhas em cascata, respeita cotas upstream e mantém sua aplicação resiliente sob carga.

Quando Usar Esta Habilidade

• Use ao chamar APIs externas que impõem limites de taxa (OpenAI, Stripe, GitHub, etc.)
• Use quando você receber erros 429 Too Many Requests ou 5xx e precisar de recuperação graciosa
• Use ao construir um cliente que deve respeitar os cabeçalhos Retry-After
• Use ao projetar um sistema que se expande para vários provedores de API
• Use quando o usuário disser "lidar com limites de taxa", "adicionar lógica de retentativa", "estratégia de backoff" ou "não ser estrangulado"

Como Funciona

Passo 1: Classificar a resposta

Determine se uma solicitação falha é retentável ou terminal.

Passo 2: Analisar cabeçalhos de limite de taxa

Sempre verifique as dicas upstream antes de calcular seu próprio atraso.

function getRetryDelay(
  response: Response,
  attempt: number,
  maxDelayMs = 60_000
): number {
  // Prefer upstream hints
  const retryAfter = response.headers.get("Retry-After");
  if (retryAfter) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds) && seconds >= 0) {
      return seconds * 1000;
    }
    // HTTP-date format
    const date = new Date(retryAfter).getTime();
    if (Number.isFinite(date)) {
      return Math.max(0, date - Date.now());
    }
  }

  // GitHub documents x-ratelimit-reset as Unix epoch seconds.
  const resetHeader = response.headers.get("x-ratelimit-reset");
  const githubReset = resetHeader === null || resetHeader.trim() === "" ? NaN : Number(resetHeader);
  if (Number.isFinite(githubReset)) {
    return Math.max(0, githubReset * 1000 - Date.now());
  }

  // Fallback: capped exponential backoff with full jitter.
  const cap = Math.min(1000 * 2 ** attempt, maxDelayMs);
  return Math.floor(Math.random() * cap);
}

As dicas upstream são esperas mínimas; nunca as trunque para retentar mais cedo. Se uma dica exceder o orçamento de operação restante, pare sem agendar outra solicitação. O limite se aplica apenas ao backoff de fallback.

Cabeçalhos de reinicialização específicos do provedor não compartilham uma unidade ou formato. Por exemplo, algumas APIs retornam durações enquanto o GitHub retorna segundos de época. Analise um cabeçalho adicional apenas após verificar a documentação atual desse provedor.

Passo 3: Implementar o loop de retentativa

async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3,
  maxElapsedMs = 120_000,
  retryNonIdempotent = false
): Promise<Response> {
  const startedAt = Date.now();
  const method = (options.method ?? "GET").toUpperCase();
  const replaySafe = ["GET", "HEAD", "OPTIONS", "PUT", "DELETE"].includes(method)
    || retryNonIdempotent;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response;

    // Terminal errors — do not retry
    if (![408, 429, 500, 502, 503, 504].includes(response.status)) {
      throw new Error(`Terminal error ${response.status}: ${response.statusText}`);
    }

    if (!replaySafe) {
      throw new Error(
        `${method} was not retried because replay safety was not explicitly established`
      );
    }

    // Retryable — but exhausted attempts
    if (attempt === maxRetries) {
      throw new Error(`Failed after ${maxRetries} retries: ${response.status}`);
    }

    const remaining = maxElapsedMs - (Date.now() - startedAt);
    const delay = getRetryDelay(response, attempt);
    if (remaining <= 0 || delay > remaining) {
      throw new Error(`Retry cannot be scheduled within ${maxElapsedMs}ms`);
    }

    // Release the connection before waiting when the body is not needed.
    await response.body?.cancel();
    console.warn(
      `Request failed (${response.status}), retrying in ${Math.round(delay)}ms (attempt ${attempt + 1}/${maxRetries})`
    );
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error("Unreachable");
}

Passo 4: Adicionar um limitador de taxa no lado do cliente (proativo)

…