Build a Resilient Client

# File: gloo_client.py
import json
import logging
import os
import random
import time
from dataclasses import dataclass, field

import requests

log = logging.getLogger("gloo_client")

API_BASE = "https://platform.ai.gloo.com"

# Someone is waiting (an interactive request or a live stream): at most 2 retries,
# with waits of a couple of seconds at most.
INTERACTIVE_MAX_ATTEMPTS = 3   # the first request plus 2 retries
LIVE_STREAM_RETRIES = 2        # full retries before any text is shown
LIVE_BACKOFF_CAP_S = 2.0

# Background work nobody is watching, streaming or not: at most 5 requests in total.
BACKGROUND_MAX_ATTEMPTS = 5    # the first request plus 4 retries
BACKGROUND_STREAM_RETRIES = 4
BACKOFF_CAP_S = 30.0

USER_FALLBACK = "The service is temporarily unavailable. Please try again."


@dataclass
class Classified:
    kind: str                  # "success" | "retry" | "fix_request" | "stop"
    status: int | None = None
    code: str | None = None    # X-Gloo-Error-Code, error.name, or detail.code
    retry_after: float | None = None
    user_message: str | None = None
    trace_id: str | None = None
    request_id: str | None = None
    raw: dict = field(default_factory=dict)


class GlooAPIError(Exception):
    def __init__(self, info: Classified):
        super().__init__(f"{info.status} {info.code}: {info.user_message}")
        self.info = info


def _retry_after(headers, error: dict) -> float | None:
    value = headers.get("Retry-After")
    if value is not None:
        try:
            return max(0.0, float(value))
        except ValueError:
            pass  # not a number of seconds; fall back to backoff
    body_value = error.get("retry_after")
    if isinstance(body_value, (int, float)):
        return max(0.0, float(body_value))
    return None


def classify(status: int, headers, body) -> Classified:
    """Turn one HTTP response into a decision. Only an explicit retryable=true retries."""
    request_id = headers.get("X-Request-Id")
    if 200 <= status < 300:
        return Classified("success", status, request_id=request_id)

    body = body if isinstance(body, dict) else {}
    error = body.get("error") if isinstance(body.get("error"), dict) else None
    detail = body.get("detail") if isinstance(body.get("detail"), dict) else None
    source = error or detail or {}

    code = (
        headers.get("X-Gloo-Error-Code")
        or source.get("name")
        or (str(source["code"]) if "code" in source else None)
    )
    if source.get("retryable") is True:
        kind = "retry"
    elif status in (400, 404, 405, 413, 422):
        kind = "fix_request"
    else:
        kind = "stop"

    return Classified(
        kind=kind,
        status=status,
        code=code,
        retry_after=_retry_after(headers, source),
        user_message=source.get("message") or USER_FALLBACK,
        trace_id=source.get("trace_id"),
        request_id=request_id,
        raw=body,
    )

// File: glooClient.ts
const API_BASE = "https://platform.ai.gloo.com";

// Someone is waiting (an interactive request or a live stream): at most 2 retries,
// with waits of a couple of seconds at most.
const INTERACTIVE_MAX_ATTEMPTS = 3; // the first request plus 2 retries
const LIVE_STREAM_RETRIES = 2; // full retries before any text is shown
const LIVE_BACKOFF_CAP_S = 2;

// Background work nobody is watching, streaming or not: at most 5 requests in total.
const BACKGROUND_MAX_ATTEMPTS = 5; // the first request plus 4 retries
const BACKGROUND_STREAM_RETRIES = 4;
const BACKOFF_CAP_S = 30;

// An upper bound on one streamed request, from the first byte to the last.
const STREAM_TIMEOUT_MS = 600_000;

const USER_FALLBACK = "The service is temporarily unavailable. Please try again.";

export type Kind = "success" | "retry" | "fix_request" | "stop";

export interface Classified {
  kind: Kind;
  status: number;
  code?: string;
  retryAfter?: number;
  userMessage?: string;
  traceId?: string;
  requestId?: string;
  raw?: unknown;
}

export class GlooAPIError extends Error {
  constructor(public info: Classified) {
    super(`${info.status} ${info.code}: ${info.userMessage}`);
  }
}

type Json = Record<string, any>;

function retryAfter(headers: Headers, error: Json): number | undefined {
  const header = headers.get("Retry-After");
  if (header !== null && header.trim() !== "" && !Number.isNaN(Number(header))) {
    return Math.max(0, Number(header));
  }
  return typeof error.retry_after === "number" ? Math.max(0, error.retry_after) : undefined;
}

export function classify(status: number, headers: Headers, body: unknown): Classified {
  const requestId = headers.get("X-Request-Id") ?? undefined;
  if (status >= 200 && status < 300) return { kind: "success", status, requestId };

  const b = (body && typeof body === "object" ? body : {}) as Json;
  const error = b.error && typeof b.error === "object" ? b.error : undefined;
  const detail = b.detail && typeof b.detail === "object" ? b.detail : undefined;
  const source: Json = error ?? detail ?? {};

  const code =
    headers.get("X-Gloo-Error-Code") ??
    source.name ??
    (source.code !== undefined ? String(source.code) : undefined);

  let kind: Kind;
  if (source.retryable === true) kind = "retry";
  else if ([400, 404, 405, 413, 422].includes(status)) kind = "fix_request";
  else kind = "stop";

  return {
    kind,
    status,
    code,
    retryAfter: retryAfter(headers, source),
    userMessage: source.message ?? USER_FALLBACK,
    traceId: source.trace_id,
    requestId,
    raw: body,
  };
}

def backoff_delay(attempt: int) -> float:
    """Background backoff after attempt N: min(2**(N-1), 30) seconds plus up to 1s of jitter."""
    return min(2 ** (attempt - 1), BACKOFF_CAP_S) + random.uniform(0, 1)


def full_jitter_delay(retry: int, base: float = 0.5, cap: float = LIVE_BACKOFF_CAP_S) -> float:
    """Short backoff when someone is waiting: random() * min(cap, base * 2**retry)."""
    return random.random() * min(cap, base * (2 ** retry))

/** Background backoff after attempt N: min(2**(N-1), 30) seconds plus up to 1s of jitter. */
export function backoffDelayS(attempt: number): number {
  return Math.min(2 ** (attempt - 1), BACKOFF_CAP_S) + Math.random();
}

/** Short backoff when someone is waiting: random() * min(cap, base * 2**retry). */
export function fullJitterDelayS(retry: number, base = 0.5, cap = LIVE_BACKOFF_CAP_S): number {
  return Math.random() * Math.min(cap, base * 2 ** retry);
}

const sleepS = (s: number) => new Promise<void>((r) => setTimeout(r, s * 1000));

def _headers() -> dict:
    return {
        "Authorization": f"Bearer {os.environ['GLOO_API_KEY']}",
        "Content-Type": "application/json",
    }


def _json_or_none(response):
    try:
        return response.json()
    except ValueError:
        return None


@dataclass
class Result:
    data: dict
    attempts: int
    request_id: str | None
    redirected_from: str | None


class GlooClient:
    def __init__(self, session=None, sleep=time.sleep, timeout=(10, 300)):
        self.session = session or requests.Session()
        self.sleep = sleep
        self.timeout = timeout

    def post(self, path: str, body: dict, *, background: bool = False,
             extra_headers: dict | None = None) -> Result:
        """Send one non-streaming request, retrying only what the API says is retryable.

        background=False: someone is waiting. 2 retries, waits of 2s at most.
        background=True: nobody is waiting. 5 requests in total, waits of 30s at most.
        """
        if background:
            max_attempts, max_wait_s = BACKGROUND_MAX_ATTEMPTS, BACKOFF_CAP_S
        else:
            max_attempts, max_wait_s = INTERACTIVE_MAX_ATTEMPTS, LIVE_BACKOFF_CAP_S

        def delay(attempt: int) -> float:
            return backoff_delay(attempt) if background else full_jitter_delay(attempt - 1)

        headers = {**_headers(), **(extra_headers or {})}
        for attempt in range(1, max_attempts + 1):
            try:
                response = self.session.post(API_BASE + path, json=body,
                                             headers=headers, timeout=self.timeout)
            except (requests.ConnectionError, requests.Timeout) as exc:
                # No response at all: plausibly transient.
                if attempt == max_attempts:
                    raise
                wait = delay(attempt)
                log.warning("transport error %s; retry %d in %.1fs", exc, attempt, wait)
                self.sleep(wait)
                continue

            payload = _json_or_none(response)
            info = classify(response.status_code, response.headers, payload)
            if info.kind == "success":
                redirected = response.headers.get("X-Gloo-Model-Redirected-From")
                if redirected:
                    log.warning("model %s is deprecated; served by %s",
                                redirected, (payload or {}).get("model"))
                return Result(payload or {}, attempt, info.request_id, redirected)

            log.warning("status=%s code=%s retryable=%s trace_id=%s request_id=%s",
                        info.status, info.code, info.kind == "retry",
                        info.trace_id, info.request_id)
            if info.kind != "retry" or attempt == max_attempts:
                raise GlooAPIError(info)

            if info.retry_after is None:
                wait = delay(attempt)
            elif info.retry_after > max_wait_s:
                raise GlooAPIError(info)  # longer than this caller can wait: fail fast
            else:
                wait = info.retry_after + random.uniform(0, 0.5)
            self.sleep(wait)
        raise AssertionError("unreachable")

function authHeaders(extra: Record<string, string> = {}): Record<string, string> {
  return {
    Authorization: `Bearer ${process.env.GLOO_API_KEY}`,
    "Content-Type": "application/json",
    ...extra,
  };
}

async function jsonOrUndefined(res: Response): Promise<unknown> {
  try {
    return await res.json();
  } catch {
    return undefined;
  }
}

export interface Result {
  data: Json;
  attempts: number;
  requestId?: string;
  redirectedFrom?: string;
}

export interface PostOptions {
  /** false (default): someone is waiting. 2 retries, waits of 2s at most.
   *  true: nobody is waiting. 5 requests in total, waits of 30s at most. */
  background?: boolean;
  headers?: Record<string, string>;
  timeoutMs?: number;
}

export class GlooClient {
  constructor(
    protected fetchImpl: typeof fetch = fetch,
    protected sleep: (s: number) => Promise<void> = sleepS,
  ) {}

  async post(path: string, body: Json, opts: PostOptions = {}): Promise<Result> {
    const maxAttempts = opts.background ? BACKGROUND_MAX_ATTEMPTS : INTERACTIVE_MAX_ATTEMPTS;
    const maxWaitS = opts.background ? BACKOFF_CAP_S : LIVE_BACKOFF_CAP_S;
    const delay = (attempt: number) =>
      opts.background ? backoffDelayS(attempt) : fullJitterDelayS(attempt - 1);

    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      let res: Response;
      try {
        res = await this.fetchImpl(API_BASE + path, {
          method: "POST",
          headers: authHeaders(opts.headers),
          body: JSON.stringify(body),
          signal: AbortSignal.timeout(opts.timeoutMs ?? 300_000),
        });
      } catch (err) {
        // No response at all: plausibly transient.
        if (attempt === maxAttempts) throw err;
        const wait = delay(attempt);
        console.warn(`transport error ${err}; retry ${attempt} in ${wait.toFixed(1)}s`);
        await this.sleep(wait);
        continue;
      }

      const payload = await jsonOrUndefined(res);
      const info = classify(res.status, res.headers, payload);
      if (info.kind === "success") {
        const redirectedFrom = res.headers.get("X-Gloo-Model-Redirected-From") ?? undefined;
        if (redirectedFrom) {
          console.warn(`model ${redirectedFrom} is deprecated; served by ${(payload as Json)?.model}`);
        }
        return { data: (payload ?? {}) as Json, attempts: attempt, requestId: info.requestId, redirectedFrom };
      }

      console.warn(
        `status=${info.status} code=${info.code} retryable=${info.kind === "retry"} ` +
          `trace_id=${info.traceId} request_id=${info.requestId}`,
      );
      if (info.kind !== "retry" || attempt === maxAttempts) throw new GlooAPIError(info);

      let wait: number;
      if (info.retryAfter === undefined) wait = delay(attempt);
      else if (info.retryAfter > maxWaitS) throw new GlooAPIError(info); // too long: fail fast
      else wait = info.retryAfter + Math.random() * 0.5;
      await this.sleep(wait);
    }
    throw new Error("unreachable");
  }
}

client = GlooClient()
try:
    result = client.post("/ai/v2/guarded/chat/completions", {
        "model": "gloo-anthropic-claude-opus-5.5",
        "messages": [{"role": "user", "content": "Suggest three themes for a youth retreat."}],
    })
    print(result.data["choices"][0]["message"]["content"])
    print(f"attempts={result.attempts} request_id={result.request_id}")
except GlooAPIError as exc:
    if exc.info.kind == "fix_request":
        print("Change the request:", exc.info.code)
    else:
        print(exc.info.user_message)  # safe to show your users

const client = new GlooClient();
try {
  const result = await client.post("/ai/v2/guarded/chat/completions", {
    model: "gloo-anthropic-claude-opus-5.5",
    messages: [{ role: "user", content: "Suggest three themes for a youth retreat." }],
  });
  console.log(result.data.choices[0].message.content);
  console.log(`attempts=${result.attempts} request_id=${result.requestId}`);
} catch (err) {
  if (err instanceof GlooAPIError && err.info.kind === "fix_request") {
    console.log("Change the request:", err.info.code);
  } else if (err instanceof GlooAPIError) {
    console.log(err.info.userMessage); // safe to show your users
  } else {
    throw err;
  }
}

result = client.post("/ai/v2/guarded/chat/completions", job_body, background=True)

const result = await client.post("/ai/v2/guarded/chat/completions", jobBody, { background: true });

@dataclass
class StreamOutcome:
    text: str = ""
    shown: bool = False
    tool_call: bool = False
    finish_reason: str | None = None
    error: dict | None = None
    transport_error: str | None = None
    http_error: Classified | None = None

    @property
    def retryable(self) -> bool:
        if self.http_error is not None:
            return self.http_error.kind == "retry"
        if self.transport_error is not None:
            return True
        return bool(self.error and self.error.get("retryable") is True)


@dataclass
class StreamResult:
    status: str  # "complete" | "content_filter" | "interrupted" | "failed"
    text: str
    last: StreamOutcome
    full_retries: int = 0
    continued: bool = False


def continuation_messages(messages: list[dict], partial: str) -> list[dict]:
    return [*messages, {
        "role": "user",
        "content": ("The previous streamed answer was interrupted after this text:\n\n"
                    f"{partial}\n\n"
                    "Continue from that point without repeating the text above."),
    }]


class GlooStreamClient(GlooClient):
    def stream_once(self, path: str, body: dict, on_delta=None) -> StreamOutcome:
        out = StreamOutcome()
        try:
            with self.session.post(API_BASE + path, json={**body, "stream": True},
                                   headers=_headers(), stream=True,
                                   timeout=self.timeout) as response:
                if response.status_code != 200:
                    out.http_error = classify(response.status_code, response.headers,
                                              _json_or_none(response))
                    return out
                response.encoding = "utf-8"  # SSE is always UTF-8; don't guess from the header
                for line in response.iter_lines(decode_unicode=True):
                    if not line or not line.startswith("data:"):
                        continue
                    data = line[len("data:"):].strip()
                    if data == "[DONE]":
                        break
                    event = json.loads(data)  # a malformed event is a transport error
                    choice = (event.get("choices") or [{}])[0]
                    delta = choice.get("delta") or {}
                    if delta.get("content"):
                        out.text += delta["content"]
                        out.shown = True
                        if on_delta:
                            on_delta(delta["content"])
                    if delta.get("tool_calls"):
                        out.tool_call = True
                    if event.get("error"):
                        out.error = event["error"]
                    if choice.get("finish_reason"):
                        out.finish_reason = choice["finish_reason"]
                        break
        except (requests.ConnectionError, requests.Timeout,
                requests.exceptions.ChunkedEncodingError, json.JSONDecodeError) as exc:
            out.transport_error = str(exc)
        if out.finish_reason is None and out.error is None and out.http_error is None \
                and out.transport_error is None:
            out.transport_error = "stream ended without a finish_reason"
        return out

    def stream(self, path: str, body: dict, *, on_delta=None, background=False) -> StreamResult:
        budget = BACKGROUND_STREAM_RETRIES if background else LIVE_STREAM_RETRIES
        cap = BACKOFF_CAP_S if background else LIVE_BACKOFF_CAP_S
        retries = 0
        while True:
            out = self.stream_once(path, body, on_delta)
            if out.finish_reason in ("stop", "length", "tool_calls"):
                return StreamResult("complete", out.text, out, retries)
            if out.finish_reason == "content_filter":
                return StreamResult("content_filter", out.text, out, retries)
            if not out.retryable:
                return StreamResult("failed", out.text, out, retries)
            if out.shown and not background:
                return self._continue_once(path, body, out, on_delta)
            if retries >= budget:
                return StreamResult("failed", out.text, out, retries)
            wait = backoff_delay(retries + 1) if background else full_jitter_delay(retries)
            server_wait = out.http_error.retry_after if out.http_error else None
            if server_wait is None and out.error:
                server_wait = out.error.get("retry_after")
            if isinstance(server_wait, (int, float)):
                if server_wait > cap:  # longer than this caller can wait: fail fast
                    return StreamResult("failed", out.text, out, retries)
                wait = server_wait
            self.sleep(wait)
            retries += 1

    def _continue_once(self, path, body, first: StreamOutcome, on_delta) -> StreamResult:
        if first.tool_call:
            return StreamResult("interrupted", first.text, first)
        self.sleep(full_jitter_delay(0))
        follow = {**body, "messages": continuation_messages(body["messages"], first.text)}
        second = self.stream_once(path, follow, on_delta)
        if second.finish_reason == "content_filter":
            status = "content_filter"  # final: show it, never continue again
        else:
            status = "complete" if second.finish_reason in ("stop", "length") else "interrupted"
        return StreamResult(status, first.text + second.text, second, continued=True)

export interface StreamOutcome {
  text: string;
  shown: boolean;
  toolCall: boolean;
  finishReason?: string;
  error?: Json;
  transportError?: string;
  httpError?: Classified;
}

export interface StreamResult {
  status: "complete" | "content_filter" | "interrupted" | "failed";
  text: string;
  last: StreamOutcome;
  fullRetries: number;
  continued: boolean;
}

function isRetryable(o: StreamOutcome): boolean {
  if (o.httpError) return o.httpError.kind === "retry";
  if (o.transportError) return true;
  return o.error?.retryable === true;
}

export function continuationMessages(messages: Json[], partial: string): Json[] {
  return [
    ...messages,
    {
      role: "user",
      content:
        "The previous streamed answer was interrupted after this text:\n\n" +
        `${partial}\n\nContinue from that point without repeating the text above.`,
    },
  ];
}

export class GlooStreamClient extends GlooClient {
  async streamOnce(path: string, body: Json, onDelta?: (t: string) => void): Promise<StreamOutcome> {
    const out: StreamOutcome = { text: "", shown: false, toolCall: false };
    try {
      const res = await this.fetchImpl(API_BASE + path, {
        method: "POST",
        headers: authHeaders(),
        body: JSON.stringify({ ...body, stream: true }),
        signal: AbortSignal.timeout(STREAM_TIMEOUT_MS),
      });
      if (res.status !== 200 || !res.body) {
        out.httpError = classify(res.status, res.headers, await jsonOrUndefined(res));
        return out;
      }
      const reader = res.body.getReader();
      const decoder = new TextDecoder();
      let buffer = "";
      read: while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        buffer += decoder.decode(value, { stream: true });
        const lines = buffer.split("\n");
        buffer = lines.pop() ?? "";
        for (const line of lines) {
          if (!line.startsWith("data:")) continue;
          const data = line.slice(5).trim();
          if (data === "[DONE]") break read;
          const event = JSON.parse(data); // a malformed event is a transport error
          const choice = event.choices?.[0] ?? {};
          const content = choice.delta?.content;
          if (content) {
            out.text += content;
            out.shown = true;
            onDelta?.(content);
          }
          if (choice.delta?.tool_calls) out.toolCall = true;
          if (event.error) out.error = event.error;
          if (choice.finish_reason) {
            out.finishReason = choice.finish_reason;
            break read;
          }
        }
      }
      await reader.cancel().catch(() => {});
    } catch (err) {
      out.transportError = String(err);
    }
    if (!out.finishReason && !out.error && !out.httpError && !out.transportError) {
      out.transportError = "stream ended without a finish_reason";
    }
    return out;
  }

  async stream(
    path: string,
    body: Json,
    opts: { onDelta?: (t: string) => void; background?: boolean } = {},
  ): Promise<StreamResult> {
    const budget = opts.background ? BACKGROUND_STREAM_RETRIES : LIVE_STREAM_RETRIES;
    const cap = opts.background ? BACKOFF_CAP_S : LIVE_BACKOFF_CAP_S;
    let retries = 0;
    while (true) {
      const out = await this.streamOnce(path, body, opts.onDelta);
      const done = (status: StreamResult["status"]): StreamResult => ({
        status, text: out.text, last: out, fullRetries: retries, continued: false,
      });
      if (["stop", "length", "tool_calls"].includes(out.finishReason ?? "")) return done("complete");
      if (out.finishReason === "content_filter") return done("content_filter");
      if (!isRetryable(out)) return done("failed");
      if (out.shown && !opts.background) return this.continueOnce(path, body, out, opts.onDelta);
      if (retries >= budget) return done("failed");

      let wait = opts.background ? backoffDelayS(retries + 1) : fullJitterDelayS(retries);
      const serverWait = out.httpError?.retryAfter ?? out.error?.retry_after;
      if (typeof serverWait === "number") {
        if (serverWait > cap) return done("failed"); // longer than this caller can wait
        wait = serverWait;
      }
      await this.sleep(wait);
      retries++;
    }
  }

  private async continueOnce(
    path: string, body: Json, first: StreamOutcome, onDelta?: (t: string) => void,
  ): Promise<StreamResult> {
    if (first.toolCall) {
      return { status: "interrupted", text: first.text, last: first, fullRetries: 0, continued: false };
    }
    await this.sleep(fullJitterDelayS(0));
    const follow = { ...body, messages: continuationMessages(body.messages, first.text) };
    const second = await this.streamOnce(path, follow, onDelta);
    const reason = second.finishReason;
    return {
      status: reason === "content_filter" ? "content_filter" // final: show it, never continue again
        : reason === "stop" || reason === "length" ? "complete" : "interrupted",
      text: first.text + second.text,
      last: second,
      fullRetries: 0,
      continued: true,
    };
  }
}

client = GlooStreamClient()
result = client.stream(
    "/ai/v2/guarded/chat/completions",
    {
        "model": "gloo-anthropic-claude-opus-5.5",
        "messages": [{"role": "user", "content": "Explain Romans 8 in simple terms."}],
    },
    on_delta=lambda text: print(text, end="", flush=True),
)
print()
if result.status == "interrupted":
    print("[The answer was cut off. Continue | Try again]")
elif result.status == "content_filter":
    pass  # final: the text shown is the answer, so offer no Continue or Try again
elif result.status == "failed":
    print("[Something went wrong. Please try again.]")

const client = new GlooStreamClient();
const result = await client.stream(
  "/ai/v2/guarded/chat/completions",
  {
    model: "gloo-anthropic-claude-opus-5.5",
    messages: [{ role: "user", content: "Explain Romans 8 in simple terms." }],
  },
  { onDelta: (text) => process.stdout.write(text) },
);
console.log();
if (result.status === "interrupted") {
  console.log("[The answer was cut off. Continue | Try again]");
} else if (result.status === "content_filter") {
  // final: the text shown is the answer, so offer no Continue or Try again
} else if (result.status === "failed") {
  console.log("[Something went wrong. Please try again.]");
}

# File: test_gloo_client.py
import os

from requests.structures import CaseInsensitiveDict

os.environ.setdefault("GLOO_API_KEY", "test-key")
from gloo_client import GlooAPIError, GlooClient


class FakeResponse:
    def __init__(self, status, body, headers=None):
        self.status_code, self._body = status, body
        self.headers = CaseInsensitiveDict(headers or {})

    def json(self):
        return self._body


class FakeSession:
    def __init__(self, responses):
        self.responses, self.calls = list(responses), 0

    def post(self, *args, **kwargs):
        self.calls += 1
        return self.responses.pop(0)


def error(code, name, retryable):
    return {"error": {"code": code, "name": name, "retryable": retryable, "message": "m"}}


def expect_error(session, **kwargs) -> GlooAPIError:
    try:
        GlooClient(session=session, sleep=waits.append).post("/x", {}, **kwargs)
    except GlooAPIError as exc:
        return exc
    raise AssertionError("expected GlooAPIError, but the call succeeded")


waits = []
session = FakeSession([
    FakeResponse(429, error(2004, "RATE_LIMIT", True), {"Retry-After": "3"}),
    FakeResponse(200, {"model": "gloo-anthropic-claude-opus-5.5"}),
])
result = GlooClient(session=session, sleep=waits.append).post("/x", {}, background=True)
assert result.attempts == 2 and 3 <= waits[0] <= 3.5, "background honors Retry-After"

session = FakeSession([FakeResponse(503, error(3003, "SERVICE_UNAVAILABLE", True),
                                    {"Retry-After": "30"})])
expect_error(session)
assert session.calls == 1, "interactive fails fast on a 30s Retry-After"

session = FakeSession([FakeResponse(500, error(3001, "INTERNAL_ERROR", False))])
exc = expect_error(session, background=True)
assert exc.info.kind == "stop" and session.calls == 1, "3001 is not retried"

session = FakeSession([FakeResponse(503, error(2002, "PROVIDER_UNAVAILABLE", True))] * 5)
expect_error(session)
assert session.calls == 3, "interactive: 2 retries"

waits.clear()
session = FakeSession([FakeResponse(503, error(2002, "PROVIDER_UNAVAILABLE", True))] * 5)
expect_error(session, background=True)
assert session.calls == 5, "background: five requests in total"
assert all(w <= 31 for w in waits), "background waits are capped at 30s plus jitter"

print("✓ all failure paths behave as expected")

// File: glooClient.test.ts
import { GlooAPIError, GlooClient } from "./glooClient";

process.env.GLOO_API_KEY ??= "test-key";

function check(condition: boolean, message: string) {
  if (!condition) throw new Error(`failed: ${message}`);
}
const error = (code: number, name: string, retryable: boolean) => ({
  error: { code, name, retryable, message: "m" },
});
const json = (status: number, body: unknown, headers: Record<string, string> = {}) =>
  new Response(JSON.stringify(body), { status, headers });

function fakeFetch(responses: Response[]) {
  const state = { calls: 0 };
  const impl = (async () => (state.calls++, responses.shift()!)) as unknown as typeof fetch;
  return { impl, state };
}
const waits: number[] = [];
const recordSleep = async (s: number) => { waits.push(s); };

async function expectError(fake: ReturnType<typeof fakeFetch>, opts = {}): Promise<GlooAPIError> {
  try {
    await new GlooClient(fake.impl, recordSleep).post("/x", {}, opts);
  } catch (err) {
    if (err instanceof GlooAPIError) return err;
    throw err;
  }
  throw new Error("failed: expected GlooAPIError, but the call succeeded");
}

async function main() {
  let fake = fakeFetch([
    json(429, error(2004, "RATE_LIMIT", true), { "Retry-After": "3" }),
    json(200, { model: "gloo-anthropic-claude-opus-5.5" }),
  ]);
  const result = await new GlooClient(fake.impl, recordSleep).post("/x", {}, { background: true });
  check(result.attempts === 2 && waits[0] >= 3 && waits[0] <= 3.5, "background honors Retry-After");

  fake = fakeFetch([json(503, error(3003, "SERVICE_UNAVAILABLE", true), { "Retry-After": "30" })]);
  await expectError(fake);
  check(fake.state.calls === 1, "interactive fails fast on a 30s Retry-After");

  fake = fakeFetch([json(500, error(3001, "INTERNAL_ERROR", false))]);
  const stop = await expectError(fake, { background: true });
  check(stop.info.kind === "stop" && fake.state.calls === 1, "3001 is not retried");

  const unavailable = () => json(503, error(2002, "PROVIDER_UNAVAILABLE", true));
  fake = fakeFetch(Array.from({ length: 5 }, unavailable));
  await expectError(fake);
  check(fake.state.calls === 3, "interactive: 2 retries");

  waits.length = 0;
  fake = fakeFetch(Array.from({ length: 5 }, unavailable));
  await expectError(fake, { background: true });
  check(fake.state.calls === 5, "background: five requests in total");
  check(waits.every((w) => w <= 31), "background waits are capped at 30s plus jitter");

  console.log("✓ all failure paths behave as expected");
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

python test_gloo_client.py

npx tsx glooClient.test.ts