@lifi/composer-sdk/dist/errors.d.cts

Public Composer SDK for building and submitting flows

import { ComposeErrorKind, SimulationRevert } from '@lifi/compose-spec';

/**
 * Machine-readable error codes returned by the SDK.
 *
 * - `NETWORK_ERROR` — The HTTP request failed (DNS, timeout, connection refused).
 * - `VALIDATION_ERROR` — The server rejected the request (HTTP 400/422).
 * - `UNAUTHENTICATED` — The request lacks valid authentication credentials (HTTP 401).
 * - `FORBIDDEN` — The server understood the request but refuses to authorise it (HTTP 403).
 * - `SERVER_ERROR` — The server returned a 5xx status.
 * - `RATE_LIMITED` — The server returned HTTP 429.
 * - `NOT_FOUND` — The requested resource does not exist (HTTP 404).
 * - `UNKNOWN_ERROR` — An unexpected error that doesn't fit other categories.
 */
type ComposeErrorCode = 'NETWORK_ERROR' | 'VALIDATION_ERROR' | 'UNAUTHENTICATED' | 'FORBIDDEN' | 'SERVER_ERROR' | 'RATE_LIMITED' | 'NOT_FOUND' | 'UNKNOWN_ERROR';
/**
 * Error class for all failures originating from the Compose SDK or API.
 *
 * Includes structured metadata beyond the error message to support
 * programmatic error handling.
 *
 * @example
 * ```ts
 * try {
 *   await builder.compile(run);
 * } catch (e) {
 *   if (isComposeError(e) && e.code === 'VALIDATION_ERROR') {
 *     console.error('Invalid request:', e.message, e.path);
 *   }
 * }
 * ```
 */
declare class ComposeError extends Error {
    readonly name = "ComposeError";
    /** Machine-readable error category. */
    readonly code: ComposeErrorCode;
    /** HTTP status code, when the error originated from an HTTP response. */
    readonly status?: number;
    /** The request URL that produced the error. */
    readonly url?: string;
    /** Server-provided error kind for finer-grained classification. */
    readonly kind?: ComposeErrorKind;
    /** JSON-pointer path to the field that caused a validation error. */
    readonly path?: string;
    /**
     * Simulation revert diagnostics attached to `simulation_revert` errors.
     * Contains the raw error bytes and decoded error candidates when the
     * backend can parse the revert reason.
     */
    readonly details?: SimulationRevert;
    constructor(code: ComposeErrorCode, message: string, options?: {
        status?: number;
        url?: string;
        cause?: unknown;
        kind?: ComposeErrorKind;
        path?: string;
        details?: SimulationRevert;
    });
}
/**
 * Type guard that narrows an unknown error to {@link ComposeError}.
 * @param e - The value to check.
 * @returns `true` if `e` is an instance of `ComposeError`.
 */
declare const isComposeError: (e: unknown) => e is ComposeError;
/**
 * Constructs a {@link ComposeError} from an HTTP error response, extracting
 * structured error details from the response body when available.
 *
 * @param status - The HTTP status code.
 * @param body - The raw response body text.
 * @param url - The request URL that produced the error.
 * @returns A `ComposeError` with the appropriate error code and metadata.
 */
declare const errorFromHttpResponse: (status: number, body: string, url: string) => ComposeError;

export { ComposeError, type ComposeErrorCode, errorFromHttpResponse, isComposeError };