Error handling

# One attempt, with the checks a shell script can make.
# A 5xx: send again with a new key, e.g. "$KEY:r1". A timeout (curl exit 28): send again with the same key.
KEY="support-bot:ticket-4822-triage"
STATUS=$(curl -sS -m 130 -o run.json -w "%{http_code}" https://api.opentype.dev/v1/runs \
  -H "Authorization: Bearer $OPENTYPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{
    "kind": "decision",
    "state": {"ticket": "I was charged twice this month."},
    "questions": {"urgent": {"type": "noul", "instructions": "reply within the hour?"}},
    "max_output_tokens": 16
  }')
case "$STATUS" in
  200|202) jq '{run_id, state, replayed}' run.json ;;
  500|503|504) echo "retry with a new key: $KEY:r1 ($(jq -r .error.code run.json))" ;;
  *) echo "fix first: $STATUS $(jq -r '.error.code + " " + .error.request_id' run.json)"; exit 1 ;;
esac

const API = "https://api.opentype.dev";
const RETRY_STATUSES = new Set([500, 503, 504]);

export class OpenTypeError extends Error {
  constructor(
    public status: number,
    public code: string | null, // null when the body was not JSON
    public requestId: string | null,
    message: string,
  ) {
    super(`${status} ${code ?? "non_json_error"}: ${message}`);
  }
}

async function readError(res: Response): Promise<OpenTypeError> {
  const text = await res.text();
  try {
    const { error } = JSON.parse(text);
    return new OpenTypeError(res.status, error.code, error.request_id, error.message);
  } catch {
    // Plain-text or empty body: keep the status and the header id.
    return new OpenTypeError(res.status, null, res.headers.get("x-request-id"), text);
  }
}

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

export async function createRun(baseKey: string, body: unknown, maxAttempts = 4) {
  let attempt = 0; // bumps the key suffix only after a 5xx
  for (let tries = 0; ; tries++) {
    const key = attempt === 0 ? baseKey : `${baseKey}:r${attempt}`;
    let res: Response;
    try {
      res = await fetch(`${API}/v1/runs`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.OPENTYPE_API_KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": key,
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(160_000), // above the 150 s maximum deadline
      });
    } catch (err) {
      // Timeout or dropped connection: the run may exist. Same key.
      if (tries + 1 >= maxAttempts) throw err;
      await sleep(backoff(tries));
      continue;
    }
    if (res.ok) return res.json(); // 200 or 202: check run.state
    const error = await readError(res);
    if (!RETRY_STATUSES.has(res.status) || tries + 1 >= maxAttempts) throw error;
    console.warn(`retrying after ${error.message} (${error.requestId})`);
    attempt++; // the failed run will not run again under its key
    await sleep(backoff(tries));
  }
}

function backoff(tries: number): number {
  const base = 1000 * 2 ** tries; // 1 s, 2 s, 4 s, ...
  return base / 2 + Math.random() * (base / 2);
}

import os
import random
import time

import requests

API = "https://api.opentype.dev"
RETRY_STATUSES = {500, 503, 504}


class OpenTypeError(Exception):
    def __init__(self, status: int, code: str | None, request_id: str | None, message: str):
        super().__init__(f"{status} {code or 'non_json_error'}: {message}")
        self.status, self.code, self.request_id = status, code, request_id


def read_error(res: requests.Response) -> OpenTypeError:
    try:
        error = res.json()["error"]
        return OpenTypeError(res.status_code, error["code"], error["request_id"], error["message"])
    except (ValueError, KeyError):
        # Plain-text or empty body: keep the status and the header id.
        return OpenTypeError(res.status_code, None, res.headers.get("x-request-id"), res.text)


def backoff(tries: int) -> float:
    base = 2**tries  # 1 s, 2 s, 4 s, ...
    return base / 2 + random.random() * base / 2


def create_run(base_key: str, body: dict, max_attempts: int = 4) -> dict:
    attempt = 0  # bumps the key suffix only after a 5xx
    for tries in range(max_attempts):
        key = base_key if attempt == 0 else f"{base_key}:r{attempt}"
        try:
            res = requests.post(
                f"{API}/v1/runs",
                headers={
                    "Authorization": f"Bearer {os.environ['OPENTYPE_API_KEY']}",
                    "Content-Type": "application/json",
                    "Idempotency-Key": key,
                },
                json=body,
                timeout=160,  # above the 150 s maximum deadline
            )
        except (requests.Timeout, requests.ConnectionError):
            # The run may exist. Same key.
            if tries + 1 >= max_attempts:
                raise
            time.sleep(backoff(tries))
            continue
        if res.ok:
            return res.json()  # 200 or 202: check run["state"]
        error = read_error(res)
        if res.status_code not in RETRY_STATUSES or tries + 1 >= max_attempts:
            raise error
        print(f"retrying after {error} ({error.request_id})")
        attempt += 1  # the failed run will not run again under its key
        time.sleep(backoff(tries))
    raise RuntimeError("unreachable")