Structured Remote Error Payloads

Build a tiny utility that turns already-consumed failed HTTP responses into structured error payloads and rebuilds errors from those payloads. The functions should lean on the dependency's typed error payload and consumed-response helpers instead of ad-hoc shapes.

Capabilities

Structured payload from a failed response

• When given a failed HTTP response plus its body text that contains JSON with error, request, and response.statusCode, produce a structured payload that preserves the parsed error fields and uses the response status for response.statusCode. @test

Fallback payload for unexpected bodies

• When the failed response body is plain text and lacks the expected structure, return a payload whose error.name defaults to Error, error.message equals the body text (or the status text if the body is empty), and response.statusCode matches the HTTP status. @test

Error reconstruction

• Given a structured payload produced from a failed response, rebuild an Error instance that uses the payload's error.name and error.message, and includes the response status code somewhere in the message; throw if the payload is missing error. @test

Implementation

@generates

API

export type StructuredErrorPayload = {
  error: {
    name: string;
    message: string;
    stack?: string;
    [key: string]: unknown;
  };
  request?: {
    method: string;
    url: string;
  };
  response: {
    statusCode: number;
  };
};

export type FailedResponseInput = {
  response: {
    ok: boolean;
    status: number;
    statusText: string;
    url: string;
    headers: {
      get(name: string): string | null;
    };
  };
  bodyText?: string;
};

export async function buildStructuredPayload(
  input: FailedResponseInput
): Promise<StructuredErrorPayload>;

export function rebuildError(payload: StructuredErrorPayload): Error;

Dependencies { .dependencies }

@backstage/errors { .dependency }

Provides typed error payload and consumed response helpers for parsing failed HTTP responses.