Jev API errors and rate limits: the complete troubleshooting guide

# jev_retry.py — raw-HTTP retry for POST /v1/systemone.
# Documented statuses: 401 · 422 · 429 · 529 (docs.typesafe.ai/api.md).
# The retry mechanics below are general engineering practice — the official
# docs publish no numeric limits, so none are assumed here.
import os
import random
import time

import requests

URL = "https://api.typesafe.ai/v1/systemone"
# Mirrors the official SDK's default retryable set ({408, 429, all 5xx});
# 529 is listed explicitly — it is TypeSafe's documented overload status.
RETRYABLE = {408, 429, 500, 502, 503, 504, 529}


def evaluate(state: str, questions: dict, max_attempts: int = 4) -> dict:
    delay = 0.5  # first backoff; doubles per attempt, capped at 5 s (SDK shape)
    resp = None

    for _ in range(max_attempts):
        resp = requests.post(
            URL,
            headers={
                "Authorization": f"Bearer {os.environ['TYPESAFE_API_KEY']}",
                "Content-Type": "application/json",
            },
            json={"model": "jev-latest", "state": state, "questions": questions},
            timeout=5.0,
        )
        if resp.status_code < 400:
            return resp.json()

        if resp.status_code not in RETRYABLE:
            # 400/401/403/404/422: identical bytes in, identical error out.
            resp.raise_for_status()

        # Honor the server's requested wait when it sends one:
        # Retry-After (seconds). The official SDK also parses retry-after-ms.
        wait = resp.headers.get("Retry-After")
        sleep_s = (
            float(wait) if wait else min(delay, 5.0) * random.uniform(0.75, 1.0)
        )
        time.sleep(sleep_s)
        delay *= 2

    resp.raise_for_status()  # budget spent on a retryable status
    raise RuntimeError("retry budget spent")

// lib/jev-retry.ts — per-attempt timeout, backoff with jitter, Retry-After
// handling, and a throw the caller can fail over on. The 1500 ms abort budget
// is the same circuit-breaker number used by the failover adapter on /jev-api.
const PRIMARY = 'https://api.typesafe.ai/v1/systemone';
// Mirrors the official SDK default ({408, 429, all 5xx}) + the documented 529.
const RETRYABLE = new Set([408, 429, 500, 502, 503, 504, 529]);

type Contract = { state: string; questions: Record<string, unknown> };

export async function evaluateWithRetry(
  contract: Contract,
  {
    attempts = 4,
    timeoutMs = 1500,
  }: { attempts?: number; timeoutMs?: number } = {},
): Promise<unknown> {
  let last: Response | undefined;

  for (let attempt = 0; attempt < attempts; attempt++) {
    if (attempt > 0 && last) {
      // Wait at least what the server asked for: retry-after-ms is the
      // millisecond form the official SDK understands; Retry-After is seconds.
      const msForm = Number(last.headers.get('retry-after-ms'));
      const sForm = Number(last.headers.get('retry-after')) * 1000;
      const asked = Number.isFinite(msForm) ? msForm : sForm;
      // ...then add full jitter on top: random(0, min(cap, base * 2^n)).
      const base = Math.min(500 * 2 ** (attempt - 1), 5000);
      await new Promise((r) =>
        setTimeout(r, Math.max(asked || 0, Math.random() * base)),
      );
    }

    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeoutMs);
    try {
      const res = await fetch(PRIMARY, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`,
        },
        body: JSON.stringify({ model: 'jev-latest', ...contract }),
        signal: controller.signal,
      });
      // 2xx, or a fix-the-request 4xx: hand it back either way.
      if (!RETRYABLE.has(res.status)) return res.json();
      last = res; // 408/429/5xx/529: back off and go around again
    } catch (err) {
      if (attempt === attempts - 1) {
        throw new Error('Jev unreachable after retries');
      }
      // AbortError / network failure: fall through and retry.
    } finally {
      clearTimeout(timer);
    }
  }

  // Budget spent on retryable statuses — surface where it died so the caller
  // can fail over to a secondary endpoint (see the adapter on /jev-api).
  throw new Error(`Jev still failing: HTTP ${last?.status ?? 'no response'}`);
}

# The official Python SDK retries for you. Defaults below are the documented
# ones (docs.typesafe.ai/sdk/python/api/retries.md), shown explicitly so you
# can tune rather than reinvent:
from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(
    retry=RetryPolicy(
        max_retries=2,             # default: 2 retries (three attempts total)
        backoff_initial=0.5,       # first backoff, seconds — doubles each attempt
        backoff_max=5.0,           # ceiling for the exponential growth
        backoff_jitter=0.25,       # random fraction subtracted from each delay
        timeout=30.0,              # total budget per SDK call, in seconds
        # default is {408, 429, all 5xx}:
        http_statuses={408, 429, 500, 502, 503, 504},
        respect_retry_after=True,  # honors Retry-After / retry-after-ms headers
    ),
)

# Connection errors and timeouts are retried by default too. When the budget
# is spent on a 429, the SDK re-raises TypeSafeRateLimitError — its documented
# retry_after_ms attribute carries the server's requested wait in
# milliseconds (None when the header is absent):
#
#     import time
#     from typesafe_sdk import TypeSafeRateLimitError
#
#     try:
#         decision = run_evaluation(client, state, questions)
#     except TypeSafeRateLimitError as err:
#         time.sleep((err.retry_after_ms or 5_000) / 1000)
#         decision = run_evaluation(client, state, questions)