Resiliência e erros

// Política de retry para chamadas à ZapCar (Node.js 18+).
const BASE = "https://api.zapcarconsulta.com.br";

// Backoff exponencial com jitter: 1 s, 2 s, 4 s… (teto de 30 s), sorteado
// entre 50% e 100% do valor para várias instâncias não repetirem juntas.
const espera = (tentativa) => {
  const teto = Math.min(30_000, 1000 * 2 ** tentativa);
  return teto / 2 + Math.random() * (teto / 2);
};
const dormir = (ms) => new Promise((r) => setTimeout(r, ms));

/**
 * Repete a MESMA requisição quando é seguro: erro de rede, timeout, 429 e
 * respostas com retryable: true. Em POST que cobra, só chame com
 * Idempotency-Key: é ela que torna a repetição segura.
 */
async function chamarComRetry(caminho, opcoes = {}, maxTentativas = 4) {
  for (let t = 0; ; t++) {
    let resp;
    try {
      resp = await fetch(BASE + caminho, {
        ...opcoes,
        headers: { Authorization: `Bearer ${process.env.ZAPCAR_API_KEY}`, ...(opcoes.headers ?? {}) },
        signal: AbortSignal.timeout(30_000),
      });
    } catch (erroDeRede) {
      // Não sabemos se o servidor processou. Com Idempotency-Key, repetir é seguro.
      if (t + 1 >= maxTentativas) throw erroDeRede;
      await dormir(espera(t));
      continue;
    }
    if (resp.status === 429 && t + 1 < maxTentativas) {
      await dormir((Number(resp.headers.get("Retry-After")) || 5) * 1000);
      continue;
    }
    const corpo = await resp.json().catch(() => ({}));
    if (resp.ok) return { status: resp.status, corpo };
    if (corpo.retryable === true && t + 1 < maxTentativas) {
      await dormir(espera(t));
      continue;
    }
    // retryable false (ou tentativas esgotadas): corrigir o pedido, não repetir.
    const erro = new Error(corpo.erro ?? `HTTP ${resp.status}`);
    Object.assign(erro, { status: resp.status, codigo: corpo.codigo, request_id: corpo.request_id });
    throw erro;
  }
}

// Uso: a chave de idempotência é estável dentro da tentativa de CONSULTA.
// const { corpo } = await chamarComRetry("/v1/consultas", {
//   method: "POST",
//   headers: { "Content-Type": "application/json", "Idempotency-Key": "pedido-984281-t1" },
//   body: JSON.stringify({ servico: "consulta", placa: "ABC1D23" }),
// });