Failure modes

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

// Returns the check, or null if Reflections could not be reached. Null means: do not generate.
async function checkUse(body: object) {
  const key = crypto.randomUUID(); // the same key on every retry
  for (let attempt = 0; attempt < 3; attempt++) {
    let res: Response;
    try {
      res = await fetch("https://app.reflections.ai/v1/checks", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
          "Reflections-Version": "2026-10-15",
          "Idempotency-Key": key,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      await sleep(2 ** attempt * 1000); // timeout or network error: the outcome is unknown
      continue;
    }
    if (res.ok) return res.json();
    const problem = await res.json().catch(() => ({})); // a proxy's 502 may not be JSON
    if (res.status === 429 || res.status >= 500 || problem.code === "idempotency_key_in_use") {
      await sleep(retryAfterMs(res) ?? 2 ** attempt * 1000);
      continue;
    }
    throw new Error(`Check rejected with ${res.status} ${problem.code}`); // a fault in the request
  }
  return null;
}

// Retry-After from Reflections is in seconds; a proxy in front of it may send an HTTP date.
function retryAfterMs(res: Response): number | undefined {
  const value = res.headers.get("Retry-After");
  if (!value) return undefined;
  const seconds = Number(value);
  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
  const date = Date.parse(value);
  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
}

import os, time, uuid, requests
from email.utils import parsedate_to_datetime

def check_use(body):
    """Returns the check, or None if Reflections could not be reached. None means: do not generate."""
    key = str(uuid.uuid4())  # the same key on every retry
    for attempt in range(3):
        try:
            res = requests.post(
                "https://app.reflections.ai/v1/checks",
                headers={
                    "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
                    "Reflections-Version": "2026-10-15",
                    "Idempotency-Key": key,
                },
                json=body,
                timeout=5,
            )
        except requests.RequestException:
            time.sleep(2 ** attempt)  # timeout or network error: the outcome is unknown
            continue
        if res.ok:
            return res.json()
        try:
            code = res.json().get("code")
        except ValueError:  # a proxy's 502 may not be JSON
            code = None
        if res.status_code == 429 or res.status_code >= 500 or code == "idempotency_key_in_use":
            wait = retry_after(res)
            time.sleep(2 ** attempt if wait is None else wait)
            continue
        res.raise_for_status()  # any other 4xx is a fault in the request
    return None

def retry_after(res):
    """Seconds to wait, or None. Reflections sends seconds; a proxy may send an HTTP date."""
    value = res.headers.get("Retry-After")
    if not value:
        return None
    try:
        return max(0.0, float(value))
    except ValueError:
        pass
    try:
        return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
    except (TypeError, ValueError):
        return None