llm-errors 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-03
+
+### Added
+
+- `normalizeError(error, options?)` — classify OpenAI, Anthropic and Gemini
+  errors into a single `NormalizedError` shape with `provider`, `category`,
+  `retryable` and `retryAfterMs`.
+- `isRetryableError(error, options?)` convenience wrapper.
+- `getRetryDelayMs(error, attempt, options?)` — respects provider-supplied
+  `Retry-After` and otherwise applies exponential backoff with jitter.
+- `parseRetryAfter` and `parseGoogleRetryDelay` low-level helpers.
+- Provider auto-detection with an explicit `{ provider }` override.
+- Transport-level error detection (timeouts, `ECONNRESET`, `AbortError`, DNS
+  failures) classified as retryable `timeout` / `server_error`.
+- Header parsing for `Headers` instances, plain objects, `Map`s and `[k, v]`
+  pair arrays.
+- Zero runtime dependencies; ESM + CJS builds with type declarations.
+
+[0.1.0]: https://github.com/slegarraga/llm-errors/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Legarraga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# llm-errors
+
+> Normalize OpenAI, Anthropic and Gemini API errors into one shape: category, retryable flag and `Retry-After` delay. **Zero dependencies.**
+
+Every LLM provider fails differently. OpenAI nests `{ error: { type, code, param } }`, Anthropic wraps `{ type: "error", error: { type } }`, Gemini speaks Google RPC status strings, and each puts retry hints in a different place. `llm-errors` collapses all of that into a single, predictable object so your retry and error-handling code stays provider-agnostic.
+
+```ts
+import { normalizeError, getRetryDelayMs } from 'llm-errors';
+
+try {
+  await client.chat.completions.create(params);
+} catch (err) {
+  const e = normalizeError(err);
+  // -> { provider: 'openai', category: 'rate_limit', retryable: true, retryAfterMs: 2000, ... }
+
+  if (e.category === 'context_length_exceeded') trimHistory();
+  else if (e.retryable) await sleep(getRetryDelayMs(e, attempt));
+  else throw err;
+}
+```
+
+## Why
+
+- **One `switch`, not three.** A `rate_limit` is a `rate_limit` whether it came from OpenAI's `code`, Anthropic's `type`, or Gemini's `RESOURCE_EXHAUSTED`.
+- **Correct retry decisions.** `insufficient_quota` and `context_length_exceeded` look like other 4xx/429s but are _not_ worth retrying. `llm-errors` separates them out.
+- **Honours `Retry-After`.** Reads the `Retry-After` header (seconds _or_ HTTP date), OpenAI's `retry-after-ms`, and Google's `RetryInfo.retryDelay` — then falls back to exponential backoff with jitter when none is given.
+- **Never throws.** Feed it an SDK error, a raw `fetch` response, plain JSON, `null`, or a string — it always returns a `NormalizedError`.
+- **Transport errors too.** Connection timeouts, resets and DNS failures (`ETIMEDOUT`, `ECONNRESET`, `AbortError`, …) have no HTTP status, yet they are retryable — `llm-errors` classifies them as `timeout` / `server_error` instead of dropping them.
+- **Zero dependencies**, ESM + CJS, fully typed.
+
+## Install
+
+```sh
+npm install llm-errors
+```
+
+## API
+
+### `normalizeError(error, options?) => NormalizedError`
+
+Classifies any value into:
+
+```ts
+interface NormalizedError {
+  provider: 'openai' | 'anthropic' | 'gemini' | 'unknown';
+  category: ErrorCategory;
+  message: string;
+  status?: number; // HTTP status, when available
+  code?: string; // provider-specific code / type
+  retryable: boolean;
+  retryAfterMs?: number; // provider-supplied delay, if any
+  raw: unknown; // the original input
+}
+```
+
+The provider is auto-detected from the error shape. Pass `{ provider }` to force it when you already know which client threw or the shape is ambiguous:
+
+```ts
+normalizeError(err, { provider: 'anthropic' });
+```
+
+### `ErrorCategory`
+
+| Category                  | Retryable | Typical cause                               |
+| ------------------------- | :-------: | ------------------------------------------- |
+| `authentication`          |    no     | Missing / invalid API key (401)             |
+| `permission`              |    no     | Key valid but not allowed (403)             |
+| `rate_limit`              |  **yes**  | Too many requests (429)                     |
+| `insufficient_quota`      |    no     | Billing / credits exhausted (429)           |
+| `context_length_exceeded` |    no     | Prompt + completion over the context window |
+| `request_too_large`       |    no     | Payload too large (413)                     |
+| `invalid_request`         |    no     | Malformed request (400 / 422)               |
+| `not_found`               |    no     | Unknown model or resource (404)             |
+| `content_filter`          |    no     | Blocked by a safety policy                  |
+| `timeout`                 |  **yes**  | Request / upstream timeout (504)            |
+| `server_error`            |  **yes**  | Upstream failure (500)                      |
+| `overloaded`              |  **yes**  | Provider temporarily overloaded (503 / 529) |
+| `unknown`                 |    no     | Could not be classified                     |
+
+### `isRetryableError(error, options?) => boolean`
+
+Shorthand for `normalizeError(error).retryable`.
+
+### `getRetryDelayMs(error, attempt, options?) => number`
+
+Returns the delay to wait before the next attempt. If the provider supplied `retryAfterMs`, that always wins. Otherwise it computes exponential backoff `baseMs * 2 ** attempt`, capped at `maxMs`, with full jitter by default.
+
+```ts
+getRetryDelayMs(e, attempt, { baseMs: 500, maxMs: 60_000, jitter: 'full' });
+```
+
+### `parseRetryAfter` / `parseGoogleRetryDelay`
+
+The low-level helpers, exported for advanced use.
+
+## Example: a provider-agnostic retry loop
+
+```ts
+import { normalizeError, getRetryDelayMs } from 'llm-errors';
+
+async function withRetries<T>(call: () => Promise<T>, max = 5): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await call();
+    } catch (err) {
+      const e = normalizeError(err);
+      if (!e.retryable || attempt >= max) throw err;
+      await new Promise((r) => setTimeout(r, getRetryDelayMs(e, attempt)));
+    }
+  }
+}
+```
+
+## Related
+
+- [`tool-schema`](https://www.npmjs.com/package/tool-schema) — convert a JSON Schema into OpenAI / Anthropic / Gemini / MCP tool schemas.
+- [`llm-messages`](https://www.npmjs.com/package/llm-messages) — convert conversations and responses between providers.
+
+## License
+
+MIT © Sebastian Legarraga

package/dist/index.cjs

@@ -0,0 +1,495 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getRetryDelayMs: () => getRetryDelayMs,
+  isRetryableError: () => isRetryableError,
+  normalizeError: () => normalizeError,
+  parseGoogleRetryDelay: () => parseGoogleRetryDelay,
+  parseRetryAfter: () => parseRetryAfter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/internal.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function firstNumber(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function getHeader(headers, name) {
+  if (!headers) {
+    return void 0;
+  }
+  const lower = name.toLowerCase();
+  if (typeof headers.get === "function") {
+    const value = headers.get(name);
+    return typeof value === "string" ? value : void 0;
+  }
+  if (Array.isArray(headers)) {
+    for (const entry of headers) {
+      if (Array.isArray(entry) && typeof entry[0] === "string" && entry[0].toLowerCase() === lower) {
+        return typeof entry[1] === "string" ? entry[1] : void 0;
+      }
+    }
+    return void 0;
+  }
+  if (isObject(headers)) {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === lower) {
+        const value = headers[key];
+        return typeof value === "string" ? value : void 0;
+      }
+    }
+  }
+  return void 0;
+}
+function readStatus(error) {
+  if (!isObject(error)) {
+    return void 0;
+  }
+  const response = isObject(error.response) ? error.response : void 0;
+  const inner = isObject(error.error) ? error.error : void 0;
+  return firstNumber(
+    error.status,
+    error.statusCode,
+    response?.status,
+    // Google encodes the status as `error.code` (a numeric HTTP status).
+    inner?.code
+  );
+}
+function readHeaders(error) {
+  if (!isObject(error)) {
+    return void 0;
+  }
+  const response = isObject(error.response) ? error.response : void 0;
+  return error.headers ?? response?.headers;
+}
+function readErrorBody(error) {
+  if (!isObject(error)) {
+    return void 0;
+  }
+  const candidates = [
+    isObject(error.error) && isObject(error.error.error) ? error.error.error : error.error,
+    isObject(error.body) ? error.body.error : void 0,
+    isObject(error.response) && isObject(error.response.data) ? error.response.data.error : void 0
+  ];
+  for (const candidate of candidates) {
+    if (isObject(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function readMessage(error, body) {
+  const fromBody = body ? firstString(body.message) : void 0;
+  if (fromBody) {
+    return fromBody;
+  }
+  if (isObject(error)) {
+    const direct = firstString(error.message);
+    if (direct) {
+      return direct;
+    }
+  }
+  if (typeof error === "string" && error.length > 0) {
+    return error;
+  }
+  return "Unknown error";
+}
+
+// src/classify.ts
+function baseCategoryFromStatus(status) {
+  switch (status) {
+    case 401:
+      return "authentication";
+    case 403:
+      return "permission";
+    case 404:
+      return "not_found";
+    case 408:
+      return "timeout";
+    case 413:
+      return "request_too_large";
+    case 400:
+    case 422:
+      return "invalid_request";
+    case 429:
+      return "rate_limit";
+    case 500:
+      return "server_error";
+    case 502:
+      return "server_error";
+    case 503:
+      return "overloaded";
+    case 504:
+      return "timeout";
+    case 529:
+      return "overloaded";
+    default:
+      break;
+  }
+  if (typeof status === "number") {
+    if (status >= 500) {
+      return "server_error";
+    }
+    if (status >= 400) {
+      return "invalid_request";
+    }
+  }
+  return "unknown";
+}
+var RETRYABLE = /* @__PURE__ */ new Set([
+  "rate_limit",
+  "server_error",
+  "overloaded",
+  "timeout"
+]);
+function isRetryableCategory(category) {
+  return RETRYABLE.has(category);
+}
+function firstHeader(headers, ...names) {
+  for (const name of names) {
+    const value = getHeader(headers, name);
+    if (value !== void 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
+
+// src/network.ts
+var RETRYABLE_CODES = {
+  ETIMEDOUT: "timeout",
+  ESOCKETTIMEDOUT: "timeout",
+  ECONNRESET: "server_error",
+  ECONNREFUSED: "server_error",
+  ECONNABORTED: "server_error",
+  EPIPE: "server_error",
+  ENOTFOUND: "server_error",
+  EAI_AGAIN: "server_error",
+  EHOSTUNREACH: "server_error",
+  ENETUNREACH: "server_error"
+};
+var NAME_PATTERNS = [
+  ["timeout", "timeout"],
+  ["aborterror", "timeout"],
+  ["connectionerror", "server_error"],
+  ["connection error", "server_error"],
+  ["fetcherror", "server_error"]
+];
+function classifyNetworkError(error) {
+  if (!isObject(error)) {
+    return void 0;
+  }
+  const code = firstString(error.code);
+  if (code && code in RETRYABLE_CODES) {
+    return { category: RETRYABLE_CODES[code], code };
+  }
+  const names = [
+    firstString(error.name),
+    firstString(error.constructor?.name)
+  ];
+  for (const name of names) {
+    if (!name) {
+      continue;
+    }
+    const haystack = name.toLowerCase();
+    for (const [pattern, category] of NAME_PATTERNS) {
+      if (haystack.includes(pattern)) {
+        return { category, code: name };
+      }
+    }
+  }
+  return void 0;
+}
+
+// src/retry.ts
+function parseRetryAfter(value, unit = "s") {
+  if (value === void 0) {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    return void 0;
+  }
+  const numeric = Number(trimmed);
+  if (Number.isFinite(numeric)) {
+    const ms = unit === "ms" ? numeric : numeric * 1e3;
+    return ms >= 0 ? ms : void 0;
+  }
+  const date = Date.parse(trimmed);
+  if (Number.isFinite(date)) {
+    return Math.max(0, date - Date.now());
+  }
+  return void 0;
+}
+function parseGoogleRetryDelay(details) {
+  if (!Array.isArray(details)) {
+    return void 0;
+  }
+  for (const detail of details) {
+    if (!isObject(detail)) {
+      continue;
+    }
+    const type = detail["@type"];
+    if (typeof type === "string" && !type.includes("RetryInfo")) {
+      continue;
+    }
+    const delay = detail.retryDelay;
+    if (typeof delay === "string") {
+      const seconds = Number(delay.replace(/s$/, ""));
+      if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1e3;
+      }
+    }
+    if (isObject(delay)) {
+      const seconds = typeof delay.seconds === "number" ? delay.seconds : Number(delay.seconds);
+      const nanos = typeof delay.nanos === "number" ? delay.nanos : 0;
+      if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1e3 + Math.round(nanos / 1e6);
+      }
+    }
+  }
+  return void 0;
+}
+function getRetryDelayMs(error, attempt, options = {}) {
+  if (typeof error.retryAfterMs === "number") {
+    return error.retryAfterMs;
+  }
+  const baseMs = options.baseMs ?? 500;
+  const maxMs = options.maxMs ?? 6e4;
+  const jitter = options.jitter ?? "full";
+  const safeAttempt = Number.isFinite(attempt) && attempt > 0 ? attempt : 0;
+  const exponential = Math.min(maxMs, baseMs * 2 ** safeAttempt);
+  if (jitter === "none") {
+    return exponential;
+  }
+  return Math.random() * exponential;
+}
+
+// src/providers/anthropic.ts
+var ANTHROPIC_TYPES = {
+  authentication_error: "authentication",
+  permission_error: "permission",
+  not_found_error: "not_found",
+  request_too_large: "request_too_large",
+  rate_limit_error: "rate_limit",
+  invalid_request_error: "invalid_request",
+  api_error: "server_error",
+  overloaded_error: "overloaded",
+  billing_error: "insufficient_quota",
+  timeout_error: "timeout"
+};
+function matches(ctx) {
+  if (firstHeader(
+    ctx.headers,
+    "anthropic-version",
+    "anthropic-ratelimit-requests-limit",
+    "anthropic-ratelimit-tokens-limit"
+  ) !== void 0) {
+    return true;
+  }
+  const body = ctx.body;
+  if (!body) {
+    return false;
+  }
+  if ("param" in body) {
+    return false;
+  }
+  const type = firstString(body.type);
+  return type !== void 0 && type in ANTHROPIC_TYPES;
+}
+function classify(ctx) {
+  const body = ctx.body ?? {};
+  const type = firstString(body.type);
+  const message = (firstString(body.message) ?? "").toLowerCase();
+  const mapped = type ? ANTHROPIC_TYPES[type] : void 0;
+  let category = mapped ?? baseCategoryFromStatus(ctx.status);
+  if (category === "invalid_request" && (message.includes("prompt is too long") || message.includes("maximum context") || message.includes("context window"))) {
+    category = "context_length_exceeded";
+  }
+  const retryAfterMs = parseRetryAfter(firstHeader(ctx.headers, "retry-after"));
+  return { category, code: type, retryAfterMs };
+}
+
+// src/providers/gemini.ts
+var RPC_STATUS = {
+  UNAUTHENTICATED: "authentication",
+  PERMISSION_DENIED: "permission",
+  NOT_FOUND: "not_found",
+  INVALID_ARGUMENT: "invalid_request",
+  FAILED_PRECONDITION: "invalid_request",
+  OUT_OF_RANGE: "invalid_request",
+  UNIMPLEMENTED: "invalid_request",
+  RESOURCE_EXHAUSTED: "rate_limit",
+  INTERNAL: "server_error",
+  UNKNOWN: "server_error",
+  ABORTED: "server_error",
+  DATA_LOSS: "server_error",
+  UNAVAILABLE: "overloaded",
+  DEADLINE_EXCEEDED: "timeout",
+  CANCELLED: "timeout"
+};
+function rpcStatus(ctx) {
+  const status = firstString(ctx.body?.status);
+  if (status && /^[A-Z][A-Z_]+$/.test(status)) {
+    return status;
+  }
+  return void 0;
+}
+function matches2(ctx) {
+  if (rpcStatus(ctx) !== void 0) {
+    return true;
+  }
+  return typeof ctx.body?.code === "number" && Array.isArray(ctx.body?.details);
+}
+function classify2(ctx) {
+  const status = rpcStatus(ctx);
+  const mapped = status ? RPC_STATUS[status] : void 0;
+  const category = mapped ?? baseCategoryFromStatus(ctx.status);
+  const retryAfterMs = parseGoogleRetryDelay(ctx.body?.details) ?? parseRetryAfter(firstHeader(ctx.headers, "retry-after"));
+  return { category, code: status, retryAfterMs };
+}
+
+// src/providers/openai.ts
+function matches3(ctx) {
+  if (firstHeader(
+    ctx.headers,
+    "openai-organization",
+    "openai-version",
+    "openai-processing-ms"
+  ) !== void 0) {
+    return true;
+  }
+  const body = ctx.body;
+  if (!body) {
+    return false;
+  }
+  if ("param" in body) {
+    return true;
+  }
+  const code = firstString(body.code);
+  return code === "context_length_exceeded" || code === "insufficient_quota" || code === "invalid_api_key";
+}
+function classify3(ctx) {
+  const body = ctx.body ?? {};
+  const type = firstString(body.type);
+  const code = firstString(body.code);
+  const identifier = `${type ?? ""} ${code ?? ""}`.toLowerCase();
+  let category = baseCategoryFromStatus(ctx.status);
+  if (identifier.includes("context_length") || identifier.includes("context window")) {
+    category = "context_length_exceeded";
+  } else if (identifier.includes("insufficient_quota")) {
+    category = "insufficient_quota";
+  } else if (identifier.includes("content_filter") || identifier.includes("content_policy")) {
+    category = "content_filter";
+  } else if (code === "invalid_api_key" || identifier.includes("authentication")) {
+    category = "authentication";
+  } else if (category === "unknown" && identifier.includes("rate_limit")) {
+    category = "rate_limit";
+  }
+  const retryAfterMs = parseRetryAfter(firstHeader(ctx.headers, "retry-after-ms"), "ms") ?? parseRetryAfter(firstHeader(ctx.headers, "retry-after"));
+  return { category, code: code ?? type, retryAfterMs };
+}
+
+// src/normalize.ts
+var DETECTORS = [
+  { name: "gemini", matches: matches2 },
+  { name: "anthropic", matches },
+  { name: "openai", matches: matches3 }
+];
+function detectProvider(ctx) {
+  for (const detector of DETECTORS) {
+    if (detector.matches(ctx)) {
+      return detector.name;
+    }
+  }
+  return "unknown";
+}
+function classifyFor(provider, ctx) {
+  switch (provider) {
+    case "openai":
+      return classify3(ctx);
+    case "anthropic":
+      return classify(ctx);
+    case "gemini":
+      return classify2(ctx);
+    default:
+      return {
+        category: baseCategoryFromStatus(ctx.status),
+        code: firstString(ctx.body?.type, ctx.body?.code)
+      };
+  }
+}
+function normalizeError(error, options = {}) {
+  const ctx = {
+    status: readStatus(error),
+    headers: readHeaders(error),
+    body: readErrorBody(error)
+  };
+  const provider = options.provider ?? detectProvider(ctx);
+  const classification = classifyFor(provider, ctx);
+  let category = classification.category;
+  let code = classification.code;
+  if (category === "unknown" && ctx.status === void 0) {
+    const network = classifyNetworkError(error);
+    if (network) {
+      category = network.category;
+      code = code ?? network.code;
+    }
+  }
+  return {
+    provider,
+    category,
+    message: readMessage(error, ctx.body),
+    status: ctx.status,
+    code,
+    retryable: isRetryableCategory(category),
+    retryAfterMs: classification.retryAfterMs,
+    raw: error
+  };
+}
+function isRetryableError(error, options = {}) {
+  return normalizeError(error, options).retryable;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getRetryDelayMs,
+  isRetryableError,
+  normalizeError,
+  parseGoogleRetryDelay,
+  parseRetryAfter
+});
+//# sourceMappingURL=index.cjs.map