Structured Fetch Error Handler

Wrap a fetch call so successful responses yield parsed JSON, while failed responses throw the dependency's standardized response error built directly from the original response. The thrown error must expose parsed error bodies and HTTP metadata so callers can inspect status, status text, and the server-provided error.

Capabilities

Successful responses

• Fetching a resource that returns HTTP 200 with JSON {"ok":true} resolves to that parsed object and does not produce a response error object @test

Structured JSON failures

• When a request returns HTTP 404 with content-type: application/json and body {"error":{"name":"NotFoundError","message":"User missing"},"response":{"statusCode":404},"request":{"method":"GET","url":"/users/123"}}, the helper throws the dependency's response error type carrying statusCode: 404, statusText: "Not Found", and a body.error matching the remote name and message @test
• That thrown object preserves the parsed error body and exposes the remote error as its cause, enabling downstream checks of cause.name and cause.message @test

Non-JSON failures

• When a request returns HTTP 503 with content-type: text/plain and body Service unavailable, the helper throws a response error whose statusCode is 503, statusText is "Service Unavailable", and whose parsed body.error.message mentions the raw body text for context @test

Implementation

@generates

API

export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;

export type FetchClientOptions = {
  /** Custom fetch implementation, defaults to global fetch */
  fetch?: FetchLike;
  /** Optional base URL prepended when path is relative */
  baseUrl?: string;
};

/**
 * Performs an HTTP request and returns parsed JSON data for successful responses.
 * Throws a structured response error built from the dependency when the response is not ok.
 */
export async function fetchJsonWithResponseError(
  path: string,
  init?: RequestInit,
  options?: FetchClientOptions
): Promise<unknown>;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Use the package's response error helper to convert non-ok fetch responses into structured errors that expose HTTP metadata, parsed bodies, and a deserialized cause. @satisfied-by