大模型 API 429、超时和 5xx 怎么排查？Node.js 重试决策表与安全实现

function parseRetryAfter(value, now = Date.now()) {
  if (!value) return null;

  const seconds = Number(value);
  if (Number.isFinite(seconds) && seconds >= 0) {
    return Math.ceil(seconds * 1000);
  }

  const date = Date.parse(value);
  if (Number.isFinite(date)) {
    return Math.max(0, date - now);
  }

  return null;
}

function backoffDelay(attempt, { baseMs = 500, capMs = 20_000 } = {}) {
  const ceiling = Math.min(capMs, baseMs * 2 ** attempt);
  return Math.floor(Math.random() * (ceiling + 1));
}

function chooseDelay({ attempt, retryAfterMs, capMs = 20_000 }) {
  const jitterMs = backoffDelay(attempt, { capMs });
  if (retryAfterMs == null) return jitterMs;
  return Math.min(capMs, Math.max(retryAfterMs, jitterMs));
}

import { setTimeout as sleep } from 'node:timers/promises';

const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);

function isRetryableNetworkError(error) {
  return ['ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN'].includes(error?.cause?.code);
}

function sanitizeErrorBody(text) {
  return String(text)
    .replace(/Bearer\s+[A-Za-z0-9._~-]+/gi, 'Bearer [REDACTED]')
    .slice(0, 1000);
}

export async function requestWithRetry(url, requestInit, options = {}) {
  const {
    maxAttempts = 4,
    attemptTimeoutMs = 30_000,
    totalBudgetMs = 70_000,
    onAttempt = () => {}
  } = options;

  const startedAt = Date.now();
  let lastError;

  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const remainingMs = totalBudgetMs - (Date.now() - startedAt);
    if (remainingMs <= 0) throw new Error('retry budget exhausted', { cause: lastError });

    const timeoutMs = Math.min(attemptTimeoutMs, remainingMs);

    try {
      const response = await fetch(url, {
        ...requestInit,
        signal: AbortSignal.timeout(timeoutMs)
      });

      if (response.ok) return response;

      const body = sanitizeErrorBody(await response.text());
      const retryable = RETRYABLE_STATUS.has(response.status);
      onAttempt({ attempt, status: response.status, retryable, errorBody: body });

      if (!retryable || attempt === maxAttempts - 1) {
        throw new Error(`model API returned ${response.status}`);
      }

      const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
      const delayMs = chooseDelay({ attempt, retryAfterMs });
      if (Date.now() - startedAt + delayMs >= totalBudgetMs) {
        throw new Error('not enough retry budget');
      }
      await sleep(delayMs);
    } catch (error) {
      lastError = error;

      // 主动超时、网络错误与代码异常必须区分；未知异常不默认重试。
      const retryable = error?.name === 'TimeoutError' || isRetryableNetworkError(error);
      onAttempt({ attempt, retryable, errorName: error?.name, errorCode: error?.cause?.code });

      if (!retryable || attempt === maxAttempts - 1) throw error;
      const delayMs = backoffDelay(attempt);
      if (Date.now() - startedAt + delayMs >= totalBudgetMs) throw error;
      await sleep(delayMs);
    }
  }

  throw lastError;
}

logger.warn({
  event: 'model_api_retry',
  requestId,
  providerConfigId: model.id,
  model: model.name,
  attempt,
  status,
  retryAfterMs,
  nextDelayMs,
  elapsedMs
});