@atproto/lex-client 0.0.0-spaces-alpha-20260818021221

package/dist/errors.d.ts

@@ -0,0 +1,277 @@
+import type { LexErrorCode, LexErrorData, LexValue } from '@atproto/lex-data';
+import { LexError } from '@atproto/lex-data';
+import { type InferMethodError, type LexValidationError, type Procedure, type Query, type ResultFailure } from '@atproto/lex-schema';
+import type { XrpcUnknownResponsePayload } from './types.js';
+import type { WWWAuthenticate } from './www-authenticate.js';
+export type { XrpcUnknownResponsePayload };
+export type DownstreamError<N extends LexErrorCode = LexErrorCode> = {
+    status: number;
+    headers?: Headers;
+    encoding?: 'application/json';
+    body: LexErrorData<N>;
+};
+/**
+ * HTTP status codes that indicate a transient error that may succeed on retry.
+ *
+ * Includes:
+ * - 408 Request Timeout
+ * - 425 Too Early
+ * - 429 Too Many Requests (rate limited)
+ * - 500 Internal Server Error
+ * - 502 Bad Gateway
+ * - 503 Service Unavailable
+ * - 504 Gateway Timeout
+ * - 522 Connection Timed Out (Cloudflare)
+ * - 524 A Timeout Occurred (Cloudflare)
+ */
+export declare const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number>;
+export { LexError };
+export type { LexErrorCode, LexErrorData };
+/**
+ * The payload structure for XRPC error responses.
+ *
+ * All XRPC errors return JSON with an `error` code and optional `message`.
+ *
+ * @typeParam N - The specific error code type
+ */
+export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> = {
+    body: LexErrorData<N>;
+    encoding: 'application/json';
+};
+/**
+ * All unsuccessful responses should follow a standard error response
+ * schema. The Content-Type should be application/json, and the payload
+ * should be a JSON object with the following fields:
+ *
+ * - `error` (string, required): type name of the error (generic ASCII
+ *   constant, no whitespace)
+ * - `message` (string, optional): description of the error, appropriate for
+ *   display to humans
+ *
+ * This function checks whether a given payload matches this schema.
+ */
+export declare function isXrpcErrorPayload(payload: XrpcUnknownResponsePayload | null | undefined): payload is XrpcErrorPayload;
+/**
+ * Abstract base class for all XRPC errors.
+ *
+ * Extends {@link LexError} and implements {@link ResultFailure} for use with
+ * safe/result-based error handling patterns.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ * @typeParam N - The error code type
+ * @typeParam TReason - The reason type for ResultFailure
+ *
+ * @see {@link XrpcResponseError} - For valid XRPC error responses
+ * @see {@link XrpcInvalidResponseError} - For invalid/unexpected responses
+ * @see {@link XrpcInternalError} - For network/internal errors
+ */
+export declare abstract class XrpcError<M extends Procedure | Query = Procedure | Query, N extends LexErrorCode = LexErrorCode, TReason = unknown> extends LexError<N> implements ResultFailure<TReason> {
+    readonly method: M;
+    name: string;
+    constructor(method: M, error: N, message?: string, options?: ErrorOptions);
+    /**
+     * @see {@link ResultFailure.success}
+     */
+    readonly success: false;
+    /**
+     * @see {@link ResultFailure.reason}
+     */
+    abstract readonly reason: TReason;
+    /**
+     * Indicates whether the error is transient and can be retried.
+     */
+    abstract shouldRetry(): boolean;
+    abstract toDownstreamError(): DownstreamError;
+    matchesSchemaErrors(): this is XrpcError<M, InferMethodError<M>>;
+}
+/**
+ * Error class for valid XRPC error responses from the server.
+ *
+ * This represents a properly formatted XRPC error where the server returned
+ * a non-2xx status with a valid JSON error payload containing `error` and
+ * optional `message` fields.
+ *
+ * Use {@link matchesSchemaErrors} to check if the error matches the method's declared
+ * error types for type-safe error handling.
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type (inferred from method or generic)
+ *
+ * @example Handling specific errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {
+ *     // Handle not found case
+ *   }
+ * }
+ * ```
+ */
+export declare class XrpcResponseError<M extends Procedure | Query = Procedure | Query> extends XrpcError<M, LexErrorCode, XrpcResponseError<M>> {
+    readonly response: Response;
+    readonly payload?: XrpcUnknownResponsePayload | undefined;
+    name: string;
+    constructor(method: M, response: Response, payload?: XrpcUnknownResponsePayload | undefined, options?: ErrorOptions);
+    get reason(): this;
+    shouldRetry(): boolean;
+    toJSON(): LexErrorData;
+    toDownstreamError(): DownstreamError;
+    get status(): number;
+    get headers(): Headers;
+    get body(): undefined | Uint8Array | LexValue;
+}
+export type { WWWAuthenticate };
+/**
+ * Error class for 401 Unauthorized XRPC responses.
+ *
+ * Extends {@link XrpcResponseError} with access to parsed WWW-Authenticate header
+ * information, useful for implementing authentication flows.
+ *
+ * Authentication errors are never retryable as they require user intervention
+ * (e.g., re-authentication, token refresh).
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type
+ *
+ * @example Handling authentication errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcAuthenticationError) {
+ *     const { DPoP } = err.wwwAuthenticate
+ *     if (DPoP?.error === 'use_dpop_nonce') {
+ *       // Handle DPoP nonce requirement
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class XrpcAuthenticationError<M extends Procedure | Query = Procedure | Query> extends XrpcResponseError<M> {
+    #private;
+    name: string;
+    shouldRetry(): boolean;
+    /**
+     * Parsed WWW-Authenticate header from the response.
+     * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).
+     */
+    get wwwAuthenticate(): WWWAuthenticate;
+}
+/**
+ * Error class for invalid or unprocessable XRPC responses from upstream servers.
+ *
+ * This occurs when the server returns a response that doesn't conform to the
+ * XRPC protocol, such as:
+ * - Missing or invalid Content-Type header
+ * - Response body that doesn't match the method's output schema
+ * - Non-JSON error responses
+ * - Responses from non-XRPC endpoints
+ *
+ * The error code is always 'InvalidResponse' and maps to HTTP 502 Bad Gateway
+ * when converted to a response. This should allow downstream clients to
+ * determine at which boundary the error occurred.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export declare class XrpcInvalidResponseError<M extends Procedure | Query = Procedure | Query> extends XrpcError<M, 'InvalidResponse', XrpcInvalidResponseError<M>> {
+    readonly response: Response;
+    readonly payload?: XrpcUnknownResponsePayload | undefined;
+    name: string;
+    constructor(method: M, response: Response, payload?: XrpcUnknownResponsePayload | undefined, message?: string, options?: ErrorOptions);
+    get reason(): this;
+    shouldRetry(): boolean;
+    toDownstreamError(): DownstreamError;
+}
+/**
+ * Error class for invalid XRPC responses that fail schema validation.
+ *
+ * This is a specific type of {@link XrpcInvalidResponseError} that indicates the
+ * upstream server returned a response that was structurally valid but did not
+ * conform to the expected schema for the method. This likely indicates a
+ * mismatch between client and server versions or an issue with the server's
+ * XRPC implementation.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export declare class XrpcResponseValidationError<M extends Procedure | Query = Procedure | Query> extends XrpcInvalidResponseError<M> {
+    readonly cause: LexValidationError;
+    name: string;
+    constructor(method: M, response: Response, payload: XrpcUnknownResponsePayload, cause: LexValidationError);
+}
+/**
+ * Error class for unexpected internal/client-side errors during XRPC requests.
+ *
+ * The error code is always 'InternalServerError' and these errors not
+ * considered retryable as they stem from unforeseen issues in the
+ * implementation.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export declare class XrpcInternalError<M extends Procedure | Query = Procedure | Query> extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {
+    name: string;
+    constructor(method: M, message?: string, options?: ErrorOptions);
+    get reason(): this;
+    shouldRetry(): boolean;
+    toJSON(): LexErrorData;
+    toDownstreamError(): DownstreamError;
+}
+/**
+ * Special case of XrpcInternalError that specifically represents errors thrown
+ * by {@link Agent.fetchHandler} during the XRPC request. This includes:
+ * - Network errors (connection refused, DNS failure)
+ * - Request timeouts
+ * - Request aborted via AbortSignal
+ *
+ * These errors are optimistically considered retryable, as many fetch errors
+ * are transient and may succeed on retry.
+ */
+export declare class XrpcFetchError<M extends Procedure | Query = Procedure | Query> extends XrpcInternalError<M> {
+    name: string;
+    constructor(method: M, cause: unknown);
+    shouldRetry(): boolean;
+    toJSON(): LexErrorData;
+    toDownstreamError(): DownstreamError;
+}
+/**
+ * Union type of all possible XRPC failure types.
+ *
+ * Used as the return type for safe/non-throwing XRPC methods. Check the
+ * `success` property to distinguish between success and failure:
+ *
+ * @typeParam M - The XRPC method type
+ *
+ * @example
+ * ```typescript
+ * const result = await client.xrpcSafe(someMethod, options)
+ * if (result.success) {
+ *   console.log(result.body) // XrpcResponse
+ * } else {
+ *   // result is XrpcFailure (XrpcResponseError | XrpcInvalidResponseError | XrpcInternalError)
+ *   console.error(result.error, result.message)
+ * }
+ * ```
+ */
+export type XrpcFailure<M extends Procedure | Query = Procedure | Query> = XrpcResponseError<M> | XrpcInvalidResponseError<M> | XrpcInternalError<M>;
+/**
+ * Converts an unknown error into an appropriate {@link XrpcFailure} type.
+ *
+ * If the error is already an XrpcFailure for the given method, returns it as-is.
+ * Otherwise, wraps it in an {@link XrpcInternalError}.
+ *
+ * @param method - The XRPC method that was called
+ * @param cause - The error to convert
+ * @returns An XrpcFailure instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await fetch(...)
+ *   // ... process response
+ * } catch (err) {
+ *   return asXrpcFailure(method, err)
+ * }
+ * ```
+ */
+export declare function asXrpcFailure<M extends Procedure | Query>(method: M, cause: unknown): XrpcFailure<M>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,388 @@
+import { LexError } from '@atproto/lex-data';
+import { lexErrorDataSchema, } from '@atproto/lex-schema';
+import { parseWWWAuthenticateHeader } from './www-authenticate.js';
+/**
+ * Mapping that allows generating an XRPC error code from an HTTP status code
+ * when the response does not contain a valid XRPC error payload. This is used
+ * to convert non-XRPC error responses from upstream servers into a standardized
+ * XRPC error for downstream clients.
+ */
+const StatusErrorCodes = new Map([
+    [400, 'InvalidRequest'],
+    [401, 'AuthenticationRequired'],
+    [403, 'Forbidden'],
+    [404, 'XRPCNotSupported'],
+    [406, 'NotAcceptable'],
+    [413, 'PayloadTooLarge'],
+    [415, 'UnsupportedMediaType'],
+    [429, 'RateLimitExceeded'],
+    [500, 'InternalServerError'],
+    [501, 'MethodNotImplemented'],
+    [502, 'UpstreamFailure'],
+    [503, 'NotEnoughResources'],
+    [504, 'UpstreamTimeout'],
+]);
+/**
+ * HTTP status codes that indicate a transient error that may succeed on retry.
+ *
+ * Includes:
+ * - 408 Request Timeout
+ * - 425 Too Early
+ * - 429 Too Many Requests (rate limited)
+ * - 500 Internal Server Error
+ * - 502 Bad Gateway
+ * - 503 Service Unavailable
+ * - 504 Gateway Timeout
+ * - 522 Connection Timed Out (Cloudflare)
+ * - 524 A Timeout Occurred (Cloudflare)
+ */
+export const RETRYABLE_HTTP_STATUS_CODES = new Set([
+    408, 425, 429, 500, 502, 503, 504, 522, 524,
+]);
+export { LexError };
+/**
+ * All unsuccessful responses should follow a standard error response
+ * schema. The Content-Type should be application/json, and the payload
+ * should be a JSON object with the following fields:
+ *
+ * - `error` (string, required): type name of the error (generic ASCII
+ *   constant, no whitespace)
+ * - `message` (string, optional): description of the error, appropriate for
+ *   display to humans
+ *
+ * This function checks whether a given payload matches this schema.
+ */
+export function isXrpcErrorPayload(payload) {
+    return (payload != null &&
+        payload.encoding === 'application/json' &&
+        lexErrorDataSchema.matches(payload.body));
+}
+/**
+ * Abstract base class for all XRPC errors.
+ *
+ * Extends {@link LexError} and implements {@link ResultFailure} for use with
+ * safe/result-based error handling patterns.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ * @typeParam N - The error code type
+ * @typeParam TReason - The reason type for ResultFailure
+ *
+ * @see {@link XrpcResponseError} - For valid XRPC error responses
+ * @see {@link XrpcInvalidResponseError} - For invalid/unexpected responses
+ * @see {@link XrpcInternalError} - For network/internal errors
+ */
+export class XrpcError extends LexError {
+    constructor(method, error, message = `${error} Lexicon RPC error`, options) {
+        super(error, message, options);
+        this.method = method;
+        this.name = 'XrpcError';
+        /**
+         * @see {@link ResultFailure.success}
+         */
+        this.success = false;
+    }
+    matchesSchemaErrors() {
+        return this.method.errors?.includes(this.error) ?? false;
+    }
+}
+/**
+ * Error class for valid XRPC error responses from the server.
+ *
+ * This represents a properly formatted XRPC error where the server returned
+ * a non-2xx status with a valid JSON error payload containing `error` and
+ * optional `message` fields.
+ *
+ * Use {@link matchesSchemaErrors} to check if the error matches the method's declared
+ * error types for type-safe error handling.
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type (inferred from method or generic)
+ *
+ * @example Handling specific errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcResponseError && err.error === 'RecordNotFound') {
+ *     // Handle not found case
+ *   }
+ * }
+ * ```
+ */
+export class XrpcResponseError extends XrpcError {
+    constructor(method, response, payload, options) {
+        const { error, message } = isXrpcErrorPayload(payload)
+            ? payload.body
+            : {
+                error: StatusErrorCodes.get(response.status) ??
+                    (response.status >= 500 ? 'UpstreamFailure' : 'InvalidRequest'),
+                message: buildResponseOverviewMessage(response),
+            };
+        super(method, error, message, options);
+        this.response = response;
+        this.payload = payload;
+        this.name = 'XrpcResponseError';
+    }
+    get reason() {
+        return this;
+    }
+    shouldRetry() {
+        return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status);
+    }
+    toJSON() {
+        // Return the original error payload if it's a valid XRPC error, otherwise
+        // convert to an XRPC error format.
+        const { payload } = this;
+        if (isXrpcErrorPayload(payload)) {
+            return payload.body;
+        }
+        return super.toJSON();
+    }
+    toDownstreamError() {
+        const { status, headers } = this.response;
+        // If the upstream server returned a 500 error, we want to return a 502 Bad
+        // Gateway to downstream clients, as the issue is with the upstream server,
+        // not us. We still return the original error code and message in the body
+        // for transparency, but we do not want to expose internal server errors
+        // from the upstream server as-is to downstream clients.
+        return {
+            status: status === 500 ? 502 : status,
+            headers: stripHopByHopHeaders(headers),
+            body: this.toJSON(),
+        };
+    }
+    get status() {
+        return this.response.status;
+    }
+    get headers() {
+        return this.response.headers;
+    }
+    get body() {
+        return this.payload?.body;
+    }
+}
+/**
+ * Error class for 401 Unauthorized XRPC responses.
+ *
+ * Extends {@link XrpcResponseError} with access to parsed WWW-Authenticate header
+ * information, useful for implementing authentication flows.
+ *
+ * Authentication errors are never retryable as they require user intervention
+ * (e.g., re-authentication, token refresh).
+ *
+ * @typeParam M - The XRPC method type
+ * @typeParam N - The error code type
+ *
+ * @example Handling authentication errors
+ * ```typescript
+ * try {
+ *   await client.xrpc(someMethod, options)
+ * } catch (err) {
+ *   if (err instanceof XrpcAuthenticationError) {
+ *     const { DPoP } = err.wwwAuthenticate
+ *     if (DPoP?.error === 'use_dpop_nonce') {
+ *       // Handle DPoP nonce requirement
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class XrpcAuthenticationError extends XrpcResponseError {
+    constructor() {
+        super(...arguments);
+        this.name = 'XrpcAuthenticationError';
+    }
+    shouldRetry() {
+        return false;
+    }
+    #wwwAuthenticateCached;
+    /**
+     * Parsed WWW-Authenticate header from the response.
+     * Contains authentication scheme parameters (e.g., Bearer realm, DPoP nonce).
+     */
+    get wwwAuthenticate() {
+        return (this.#wwwAuthenticateCached ??=
+            parseWWWAuthenticateHeader(this.response.headers.get('www-authenticate')) ?? {});
+    }
+}
+/**
+ * Error class for invalid or unprocessable XRPC responses from upstream servers.
+ *
+ * This occurs when the server returns a response that doesn't conform to the
+ * XRPC protocol, such as:
+ * - Missing or invalid Content-Type header
+ * - Response body that doesn't match the method's output schema
+ * - Non-JSON error responses
+ * - Responses from non-XRPC endpoints
+ *
+ * The error code is always 'InvalidResponse' and maps to HTTP 502 Bad Gateway
+ * when converted to a response. This should allow downstream clients to
+ * determine at which boundary the error occurred.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export class XrpcInvalidResponseError extends XrpcError {
+    constructor(method, response, payload, message = buildResponseOverviewMessage(response), options) {
+        super(method, 'InvalidResponse', message, options);
+        this.response = response;
+        this.payload = payload;
+        this.name = 'XrpcInvalidResponseError';
+    }
+    get reason() {
+        return this;
+    }
+    shouldRetry() {
+        return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status);
+    }
+    toDownstreamError() {
+        return { status: 502, body: this.toJSON() };
+    }
+}
+/**
+ * Error class for invalid XRPC responses that fail schema validation.
+ *
+ * This is a specific type of {@link XrpcInvalidResponseError} that indicates the
+ * upstream server returned a response that was structurally valid but did not
+ * conform to the expected schema for the method. This likely indicates a
+ * mismatch between client and server versions or an issue with the server's
+ * XRPC implementation.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export class XrpcResponseValidationError extends XrpcInvalidResponseError {
+    constructor(method, response, payload, cause) {
+        super(method, response, payload, `Invalid response payload: ${cause.message}`, { cause });
+        this.cause = cause;
+        this.name = 'XrpcResponseValidationError';
+    }
+}
+/**
+ * Error class for unexpected internal/client-side errors during XRPC requests.
+ *
+ * The error code is always 'InternalServerError' and these errors not
+ * considered retryable as they stem from unforeseen issues in the
+ * implementation.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export class XrpcInternalError extends XrpcError {
+    constructor(method, message, options) {
+        super(method, 'InternalServerError', message ?? 'Unable to fulfill XRPC request', options);
+        this.name = 'XrpcInternalError';
+    }
+    get reason() {
+        return this;
+    }
+    shouldRetry() {
+        return false;
+    }
+    toJSON() {
+        // @NOTE Do not expose internal error details to downstream clients
+        return { error: this.error, message: 'Internal Server Error' };
+    }
+    toDownstreamError() {
+        return { status: 500, body: this.toJSON() };
+    }
+}
+/**
+ * Special case of XrpcInternalError that specifically represents errors thrown
+ * by {@link Agent.fetchHandler} during the XRPC request. This includes:
+ * - Network errors (connection refused, DNS failure)
+ * - Request timeouts
+ * - Request aborted via AbortSignal
+ *
+ * These errors are optimistically considered retryable, as many fetch errors
+ * are transient and may succeed on retry.
+ */
+export class XrpcFetchError extends XrpcInternalError {
+    constructor(method, cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(method, `Unexpected fetchHandler() error: ${message}`, { cause });
+        this.name = 'XrpcFetchError';
+    }
+    shouldRetry() {
+        // Ideally, we would inspect the reason to determine if it's retryable (by
+        // detecting network errors, timeouts, etc.). Since these cases are highly
+        // platform-dependent, we optimistically assume all fetch errors are
+        // transient and retryable.
+        return true;
+    }
+    toJSON() {
+        // @NOTE Do not expose internal error details to downstream clients
+        return { error: this.error, message: 'Failed to perform upstream request' };
+    }
+    toDownstreamError() {
+        // While it might technically be a 500 error, we use 502 Bad Gateway here to
+        // indicate that the error occurred while communicating with the upstream
+        // server, allowing downstream clients to distinguish between errors in our
+        // internal processing (500) and errors in the upstream server or network
+        // (502).
+        return { status: 502, body: this.toJSON() };
+    }
+}
+/**
+ * Converts an unknown error into an appropriate {@link XrpcFailure} type.
+ *
+ * If the error is already an XrpcFailure for the given method, returns it as-is.
+ * Otherwise, wraps it in an {@link XrpcInternalError}.
+ *
+ * @param method - The XRPC method that was called
+ * @param cause - The error to convert
+ * @returns An XrpcFailure instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const response = await fetch(...)
+ *   // ... process response
+ * } catch (err) {
+ *   return asXrpcFailure(method, err)
+ * }
+ * ```
+ */
+export function asXrpcFailure(method, cause) {
+    if (cause instanceof XrpcResponseError ||
+        cause instanceof XrpcInvalidResponseError ||
+        cause instanceof XrpcInternalError) {
+        if (cause.method === method)
+            return cause;
+    }
+    return new XrpcInternalError(method, undefined, { cause });
+}
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+function stripHopByHopHeaders(headers) {
+    const result = new Headers(headers);
+    // Remove statically known hop-by-hop headers
+    for (const name of HOP_BY_HOP_HEADERS) {
+        result.delete(name);
+    }
+    // Remove headers listed in the "Connection" header
+    const connection = headers.get('connection');
+    if (connection) {
+        for (const name of connection.split(',')) {
+            result.delete(name.trim());
+        }
+    }
+    // These are not actually hop-by-hop headers, but we remove them because the
+    // upstream payload gets parsed and re-serialized, so content length and
+    // encoding may no longer be accurate.
+    result.delete('content-length');
+    result.delete('content-encoding');
+    return result;
+}
+function buildResponseOverviewMessage(response) {
+    if (response.status < 400) {
+        return `Upstream server responded with an invalid status code (${response.status})`;
+    }
+    return `Upstream server responded with a ${response.status} error`;
+}
+//# sourceMappingURL=errors.js.map