llm-errors 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.4] - 2026-06-05
+
+### Added
+
+- Added a public provider error fixture corpus for OpenAI, Anthropic, Gemini and
+  transport-level failures, covering SDK-like objects, parsed fetch responses
+  and expected normalized outputs.
+- Added fixture-driven regression tests and published `fixtures/` in the npm
+  package.
+
 ## [0.1.3] - 2026-06-04
 
 ### Changed
@@ -44,4 +54,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   pair arrays.
 - Zero runtime dependencies; ESM + CJS builds with type declarations.
 
+[0.1.4]: https://github.com/slegarraga/llm-errors/releases/tag/v0.1.4
+[0.1.3]: https://github.com/slegarraga/llm-errors/releases/tag/v0.1.3
+[0.1.2]: https://github.com/slegarraga/llm-errors/releases/tag/v0.1.2
+[0.1.1]: https://github.com/slegarraga/llm-errors/releases/tag/v0.1.1
 [0.1.0]: https://github.com/slegarraga/llm-errors/releases/tag/v0.1.0

package/README.md

@@ -9,6 +9,9 @@
 
 > Normalize OpenAI, Anthropic and Gemini API errors into one shape: category, retryable flag and `Retry-After` delay. **Zero dependencies.**
 
+Security posture is tracked in [docs/security-posture.md](./docs/security-posture.md),
+including CodeQL, OpenSSF Scorecard, Dependabot and branch rules.
+
 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
@@ -41,6 +44,17 @@ try {
 npm install llm-errors
 ```
 
+## Fixture corpus
+
+The npm package includes a public fixture corpus under
+[`fixtures/`](./fixtures/README.md). It pairs raw SDK-like, fetch-like and
+transport-level provider errors with the normalized output expected from
+`normalizeError`.
+
+These fixtures are useful for downstream regression tests when you want to
+verify provider-portable retry and error handling without importing OpenAI,
+Anthropic or Gemini SDKs.
+
 ## API
 
 ### `normalizeError(error, options?) => NormalizedError`

package/fixtures/README.md

@@ -0,0 +1,25 @@
+# Provider Error Fixtures
+
+This corpus contains redacted, synthetic examples of provider error shapes that
+`llm-errors` supports. The files are intentionally small JSON fixtures so they
+can be reused by downstream test suites without importing any provider SDK.
+
+## Layout
+
+- `cases/` contains raw SDK-like, fetch-like and transport-level inputs.
+- `expected/` contains the normalized output for the matching case path.
+
+For example, `cases/openai/sdk-rate-limit.json` is paired with
+`expected/openai/sdk-rate-limit.json`.
+
+## Scope
+
+The corpus covers:
+
+- OpenAI SDK `APIError`-style objects and parsed fetch responses.
+- Anthropic SDK envelopes and parsed fetch responses.
+- Gemini / Google RPC error envelopes.
+- Transport failures such as Node timeout codes and browser abort errors.
+
+The fixtures are not recordings of private traffic and do not contain API keys,
+request IDs, account IDs or user content.

package/fixtures/cases/anthropic/fetch-context-length.json

@@ -0,0 +1,17 @@
+{
+  "name": "Anthropic parsed fetch response prompt too long",
+  "shape": "anthropic-fetch-parsed-body",
+  "error": {
+    "status": 400,
+    "headers": {
+      "anthropic-version": "2023-06-01"
+    },
+    "body": {
+      "type": "error",
+      "error": {
+        "type": "invalid_request_error",
+        "message": "prompt is too long: 250000 tokens > 200000 maximum"
+      }
+    }
+  }
+}

package/fixtures/cases/anthropic/fetch-rate-limit.json

@@ -0,0 +1,18 @@
+{
+  "name": "Anthropic parsed fetch response rate limit",
+  "shape": "anthropic-fetch-parsed-body",
+  "error": {
+    "status": 429,
+    "headers": {
+      "anthropic-ratelimit-requests-limit": "50",
+      "retry-after": "30"
+    },
+    "body": {
+      "type": "error",
+      "error": {
+        "type": "rate_limit_error",
+        "message": "rate limit exceeded"
+      }
+    }
+  }
+}

package/fixtures/cases/anthropic/sdk-overloaded-529.json

@@ -0,0 +1,17 @@
+{
+  "name": "Anthropic SDK overloaded response",
+  "shape": "anthropic-sdk-apierror",
+  "error": {
+    "status": 529,
+    "headers": {
+      "anthropic-version": "2023-06-01"
+    },
+    "error": {
+      "type": "error",
+      "error": {
+        "type": "overloaded_error",
+        "message": "Overloaded"
+      }
+    }
+  }
+}

package/fixtures/cases/gemini/fetch-unavailable.json

@@ -0,0 +1,19 @@
+{
+  "name": "Gemini parsed fetch response unavailable",
+  "shape": "google-rpc-fetch-parsed-body",
+  "error": {
+    "response": {
+      "status": 503,
+      "headers": {
+        "retry-after": "4"
+      },
+      "data": {
+        "error": {
+          "code": 503,
+          "message": "The model is overloaded. Please try again later.",
+          "status": "UNAVAILABLE"
+        }
+      }
+    }
+  }
+}

package/fixtures/cases/gemini/rpc-permission-denied.json

@@ -0,0 +1,11 @@
+{
+  "name": "Gemini Google RPC permission denied",
+  "shape": "google-rpc-error-envelope",
+  "error": {
+    "error": {
+      "code": 403,
+      "message": "The caller does not have permission.",
+      "status": "PERMISSION_DENIED"
+    }
+  }
+}

package/fixtures/cases/gemini/rpc-resource-exhausted.json

@@ -0,0 +1,17 @@
+{
+  "name": "Gemini Google RPC resource exhausted",
+  "shape": "google-rpc-error-envelope",
+  "error": {
+    "error": {
+      "code": 429,
+      "message": "Resource has been exhausted.",
+      "status": "RESOURCE_EXHAUSTED",
+      "details": [
+        {
+          "@type": "type.googleapis.com/google.rpc.RetryInfo",
+          "retryDelay": "17s"
+        }
+      ]
+    }
+  }
+}

package/fixtures/cases/network/abort-error.json

@@ -0,0 +1,8 @@
+{
+  "name": "Browser fetch abort",
+  "shape": "dom-abort-error",
+  "error": {
+    "name": "AbortError",
+    "message": "The operation was aborted."
+  }
+}

package/fixtures/cases/network/node-timeout.json

@@ -0,0 +1,9 @@
+{
+  "name": "Node transport timeout",
+  "shape": "node-error-code",
+  "error": {
+    "name": "Error",
+    "message": "connect ETIMEDOUT",
+    "code": "ETIMEDOUT"
+  }
+}

package/fixtures/cases/openai/fetch-context-length.json

@@ -0,0 +1,18 @@
+{
+  "name": "OpenAI parsed fetch response context length",
+  "shape": "openai-fetch-parsed-body",
+  "error": {
+    "status": 400,
+    "headers": {
+      "openai-processing-ms": "42"
+    },
+    "body": {
+      "error": {
+        "message": "This model's maximum context length is 128000 tokens.",
+        "type": "invalid_request_error",
+        "code": "context_length_exceeded",
+        "param": "messages"
+      }
+    }
+  }
+}

package/fixtures/cases/openai/sdk-insufficient-quota.json

@@ -0,0 +1,13 @@
+{
+  "name": "OpenAI SDK APIError insufficient quota",
+  "shape": "openai-sdk-apierror",
+  "error": {
+    "status": 429,
+    "error": {
+      "message": "You exceeded your current quota.",
+      "type": "insufficient_quota",
+      "code": "insufficient_quota",
+      "param": null
+    }
+  }
+}

package/fixtures/cases/openai/sdk-rate-limit.json

@@ -0,0 +1,18 @@
+{
+  "name": "OpenAI SDK APIError rate limit",
+  "shape": "openai-sdk-apierror",
+  "error": {
+    "status": 429,
+    "headers": {
+      "openai-version": "2020-10-01",
+      "retry-after-ms": "1250",
+      "retry-after": "2"
+    },
+    "error": {
+      "message": "Rate limit reached for requests",
+      "type": "rate_limit_error",
+      "code": "rate_limit_exceeded",
+      "param": null
+    }
+  }
+}

package/fixtures/expected/anthropic/fetch-context-length.json

@@ -0,0 +1,8 @@
+{
+  "provider": "anthropic",
+  "category": "context_length_exceeded",
+  "message": "prompt is too long: 250000 tokens > 200000 maximum",
+  "status": 400,
+  "code": "invalid_request_error",
+  "retryable": false
+}

package/fixtures/expected/anthropic/fetch-rate-limit.json

@@ -0,0 +1,9 @@
+{
+  "provider": "anthropic",
+  "category": "rate_limit",
+  "message": "rate limit exceeded",
+  "status": 429,
+  "code": "rate_limit_error",
+  "retryable": true,
+  "retryAfterMs": 30000
+}

package/fixtures/expected/anthropic/sdk-overloaded-529.json

@@ -0,0 +1,8 @@
+{
+  "provider": "anthropic",
+  "category": "overloaded",
+  "message": "Overloaded",
+  "status": 529,
+  "code": "overloaded_error",
+  "retryable": true
+}

package/fixtures/expected/gemini/fetch-unavailable.json

@@ -0,0 +1,9 @@
+{
+  "provider": "gemini",
+  "category": "overloaded",
+  "message": "The model is overloaded. Please try again later.",
+  "status": 503,
+  "code": "UNAVAILABLE",
+  "retryable": true,
+  "retryAfterMs": 4000
+}

package/fixtures/expected/gemini/rpc-permission-denied.json

@@ -0,0 +1,8 @@
+{
+  "provider": "gemini",
+  "category": "permission",
+  "message": "The caller does not have permission.",
+  "status": 403,
+  "code": "PERMISSION_DENIED",
+  "retryable": false
+}

package/fixtures/expected/gemini/rpc-resource-exhausted.json

@@ -0,0 +1,9 @@
+{
+  "provider": "gemini",
+  "category": "rate_limit",
+  "message": "Resource has been exhausted.",
+  "status": 429,
+  "code": "RESOURCE_EXHAUSTED",
+  "retryable": true,
+  "retryAfterMs": 17000
+}

package/fixtures/expected/network/abort-error.json

@@ -0,0 +1,7 @@
+{
+  "provider": "unknown",
+  "category": "timeout",
+  "message": "The operation was aborted.",
+  "code": "AbortError",
+  "retryable": true
+}

package/fixtures/expected/network/node-timeout.json

@@ -0,0 +1,7 @@
+{
+  "provider": "unknown",
+  "category": "timeout",
+  "message": "connect ETIMEDOUT",
+  "code": "ETIMEDOUT",
+  "retryable": true
+}

package/fixtures/expected/openai/fetch-context-length.json

@@ -0,0 +1,8 @@
+{
+  "provider": "openai",
+  "category": "context_length_exceeded",
+  "message": "This model's maximum context length is 128000 tokens.",
+  "status": 400,
+  "code": "context_length_exceeded",
+  "retryable": false
+}

package/fixtures/expected/openai/sdk-insufficient-quota.json

@@ -0,0 +1,8 @@
+{
+  "provider": "openai",
+  "category": "insufficient_quota",
+  "message": "You exceeded your current quota.",
+  "status": 429,
+  "code": "insufficient_quota",
+  "retryable": false
+}

package/fixtures/expected/openai/sdk-rate-limit.json

@@ -0,0 +1,9 @@
+{
+  "provider": "openai",
+  "category": "rate_limit",
+  "message": "Rate limit reached for requests",
+  "status": 429,
+  "code": "rate_limit_exceeded",
+  "retryable": true,
+  "retryAfterMs": 1250
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-errors",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Normalize OpenAI, Anthropic and Gemini API errors into one shape: category, retryable flag and Retry-After delay. Zero dependencies.",
   "keywords": [
     "openai",
@@ -46,6 +46,7 @@
   },
   "files": [
     "dist",
+    "fixtures",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"