RegistryClient should expose structured HTTP errors

[bokelley]

Summary

RegistryClient throws plain Error instances for non-2xx responses and encodes the HTTP status and response body into a formatted message:

throw new Error(`Registry request failed (${res.status}): ${this.preview(text)}`)

Consumers that need correct retry, rate-limit, or classification behavior must parse SDK error strings. This is brittle duplication across every production integration and can silently break if wording changes or the 200-character preview truncates the relevant JSON field.

Downstream example: https://github.com/scope3data/agentic-api/blob/main/apps/api/src/services/v2/property-list.service.ts

That integration currently maintains regex helpers for both:

• Registry request failed (NNN) to recover the HTTP status; and
• a JSON retryAfter field embedded in the error message to recover rate-limit timing.

Expected

Export a stable typed registry HTTP error, for example:

class RegistryRequestError extends Error {
  status: number
  method?: string
  retryAfterMs?: number
  details?: unknown
}

The exact shape is a maintainer choice. The important contract is that consumers can classify HTTP failures without parsing message. The human-readable message can remain unchanged for compatibility.

Acceptance criteria

• All RegistryClient request methods throw the same exported typed error for non-2xx HTTP responses.
• The HTTP status is available as a numeric field.
• Rate-limit timing is exposed structurally when supplied through Retry-After and/or the registry's JSON error payload.
• A bounded parsed error payload or stable details field is available when safe; callers do not need to regex the body preview.
• Timeout/network errors remain distinguishable from HTTP response errors.
• Existing human-readable messages remain useful and do not expose credentials or sensitive headers.
• Tests cover at least 404, 429 with retry timing, 500, and an unreadable/non-JSON response body.

Why this belongs in the SDK

The SDK owns the HTTP transport and has the Response before reducing it to a string. Downstream callers cannot recover reliable structured data afterward, so a shared SDK error is the only place to eliminate string parsing consistently.

[bokelley]

Triage

Classification: Feature request — typed HTTP error class for RegistryClient
Bucket(s): library
Status: ready-to-implement

What the experts said:

• code-reviewer: Non-breaking (minor, not patch); two mechanical blockers — getFeed (line 1141) has its own throw new Error(...) outside the five private helpers, so all 6 throw sites must be updated; Retry-After HTTP-date strings parse to NaN via parseInt — must guard with if (!isNaN(secs)). Shape otherwise sound; no new security surface (API key is header-only, readBody cap already bounds response size).
• dx-expert: High DX improvement; eliminates a class of per-integration string-parsing shims (real downstream evidence). Concrete design guidance: RegistryRequestError is the safe name (RegistryError collides with the generated OpenAPI type exported at registry/index.ts:199); export from both src/lib/registry/index.ts and src/lib/index.ts (mirrors FeedStreamHttpError precedent); details?: Record<string, unknown> over details?: unknown for agent-readable ergonomics; export an isRegistryRequestError(e): e is RegistryRequestError type guard (avoids instanceof failure across Jest/bundler module splits).

My take: Both experts converge. Changing from throw new Error(...) to throw new RegistryRequestError(...) is non-breaking — instanceof Error stays true and the message string is unchanged; only error.name / error.constructor.name change. Changeset type should be minor.

Implementation scope:

• New class in src/lib/registry/index.ts (or a companion file):

  export class RegistryRequestError extends Error {
    readonly status: number;
    readonly method: string;          // required — all callers know the verb
    readonly retryAfterMs?: number;   // parse Retry-After header; guard NaN (HTTP-date form)
    readonly details?: Record<string, unknown>;  // bounded parsed body; undefined if non-JSON
  }
  export function isRegistryRequestError(e: unknown): e is RegistryRequestError { ... }

• Update all 6 throw sites: the five private helpers (get, post, postFormData, put, deleteRequest) and the explicit !res.ok branch in getFeed (line 1141). A private throwHttpError(res, text, method) helper prevents future drift.
• Retry-After parsing: read header; const secs = parseInt(val, 10); if (!isNaN(secs)) retryAfterMs = secs * 1000; — silently drops the HTTP-date form rather than propagating NaN.
• details: attempt JSON.parse(text) on the error body; set only when result is Record<string, unknown>; leave undefined for non-JSON or array shapes. Body is already capped by readBody/maxBodyBytes.
• Re-export from src/lib/index.ts alongside the FeedStream* class exports.
• Tests: cover 404 (with and without nullOn404), 429 with delta-seconds Retry-After, 429 with HTTP-date Retry-After (confirm retryAfterMs === undefined, not NaN), 500, and non-JSON body. All six methods should be exercised or the private helper tested directly.
• Changeset: minor — new exported class and type guard.
• Required checks: npm run ci:quick; npm run ci:docs-check if TypeDoc annotations are added to the new class.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01365YNa8cR7QQFgywm1nPzK

---

Generated by Claude Code