@nktkas/hyperliquid 0.30.3 → 0.32.0

package/script/utils/_symbolConverter.js

@@ -0,0 +1,221 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymbolConverter = void 0;
+const mod_js_1 = require("../api/info/mod.js");
+/**
+ * Utility class for converting asset symbols to their corresponding IDs and size decimals.
+ * Supports perpetuals, spot markets, and optional builder dexs.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const converter = await SymbolConverter.create({ transport });
+ *
+ * // By default, dexs are not loaded; specify them when creating an instance
+ * // const converter = await SymbolConverter.create({ transport, dexs: ["test"] });
+ *
+ * const btcId = converter.getAssetId("BTC"); // perpetual → 0
+ * const hypeUsdcId = converter.getAssetId("HYPE/USDC"); // spot market → 10107
+ * const dexAbcId = converter.getAssetId("test:ABC"); // builder dex (if enabled) → 110000
+ *
+ * const btcSzDecimals = converter.getSzDecimals("BTC"); // perpetual → 5
+ * const hypeUsdcSzDecimals = converter.getSzDecimals("HYPE/USDC"); // spot market → 2
+ * const dexAbcSzDecimals = converter.getSzDecimals("test:ABC"); // builder dex (if enabled) → 0
+ *
+ * const spotPairId = converter.getSpotPairId("HFUN/USDC"); // → "@2"
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids
+ */
+class SymbolConverter {
+    _transport;
+    _dexOption;
+    _nameToAssetId = new Map();
+    _nameToSzDecimals = new Map();
+    _nameToSpotPairId = new Map();
+    /**
+     * Creates a new SymbolConverter instance, but does not initialize it.
+     * Run {@link reload} to load asset data or use {@link create} to create and initialize in one step.
+     *
+     * @param options Configuration options including transport and optional dex support.
+     */
+    constructor(options) {
+        this._transport = options.transport;
+        this._dexOption = options.dexs ?? false;
+    }
+    /**
+     * Create and initialize a SymbolConverter instance.
+     *
+     * @param options Configuration options including transport and optional dex support.
+     * @return Initialized SymbolConverter instance.
+     *
+     * @example
+     * ```ts
+     * import { HttpTransport } from "@nktkas/hyperliquid";
+     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+     *
+     * const transport = new HttpTransport(); // or `WebSocketTransport`
+     * const converter = await SymbolConverter.create({ transport });
+     * ```
+     */
+    static async create(options) {
+        const instance = new SymbolConverter(options);
+        await instance.reload();
+        return instance;
+    }
+    /**
+     * Reload asset mappings from the API.
+     *
+     * Useful for refreshing data when new assets are added.
+     */
+    async reload() {
+        const config = { transport: this._transport };
+        const needDexs = this._dexOption === true || (Array.isArray(this._dexOption) && this._dexOption.length > 0);
+        const [perpMetaData, spotMetaData, perpDexsData] = await Promise.all([
+            (0, mod_js_1.meta)(config),
+            (0, mod_js_1.spotMeta)(config),
+            needDexs ? (0, mod_js_1.perpDexs)(config) : undefined,
+        ]);
+        if (!perpMetaData?.universe?.length) {
+            throw new Error("Invalid perpetual metadata response");
+        }
+        if (!spotMetaData?.universe?.length || !spotMetaData?.tokens?.length) {
+            throw new Error("Invalid spot metadata response");
+        }
+        this._nameToAssetId.clear();
+        this._nameToSzDecimals.clear();
+        this._nameToSpotPairId.clear();
+        this._processDefaultPerps(perpMetaData);
+        this._processSpotAssets(spotMetaData);
+        // Only process builder dexs if dex support is enabled
+        if (perpDexsData) {
+            await this._processBuilderDexs(perpDexsData);
+        }
+    }
+    _processDefaultPerps(perpMetaData) {
+        perpMetaData.universe.forEach((asset, index) => {
+            this._nameToAssetId.set(asset.name, index);
+            this._nameToSzDecimals.set(asset.name, asset.szDecimals);
+        });
+    }
+    async _processBuilderDexs(perpDexsData) {
+        if (!perpDexsData || perpDexsData.length <= 1)
+            return;
+        const builderDexs = perpDexsData
+            .map((dex, index) => ({ dex, index }))
+            .filter((item) => {
+            return item.index > 0 && item.dex !== null && item.dex.name.length > 0;
+        });
+        if (builderDexs.length === 0)
+            return;
+        // Filter dexs based on the dexOption
+        const dexsToProcess = Array.isArray(this._dexOption)
+            ? builderDexs.filter((item) => this._dexOption.includes(item.dex.name))
+            : builderDexs; // true means process all
+        if (dexsToProcess.length === 0)
+            return;
+        const config = { transport: this._transport };
+        const results = await Promise.allSettled(dexsToProcess.map((item) => (0, mod_js_1.meta)(config, { dex: item.dex.name })));
+        results.forEach((result, idx) => {
+            if (result.status !== "fulfilled")
+                return;
+            this._processBuilderDexResult(result.value, dexsToProcess[idx].index);
+        });
+    }
+    _processBuilderDexResult(dexMeta, perpDexIndex) {
+        const offset = 100000 + perpDexIndex * 10000;
+        dexMeta.universe.forEach((asset, index) => {
+            const assetId = offset + index;
+            this._nameToAssetId.set(asset.name, assetId);
+            this._nameToSzDecimals.set(asset.name, asset.szDecimals);
+        });
+    }
+    _processSpotAssets(spotMetaData) {
+        const tokenMap = new Map();
+        spotMetaData.tokens.forEach((token) => {
+            tokenMap.set(token.index, { name: token.name, szDecimals: token.szDecimals });
+        });
+        spotMetaData.universe.forEach((market) => {
+            if (market.tokens.length < 2)
+                return;
+            const baseToken = tokenMap.get(market.tokens[0]);
+            const quoteToken = tokenMap.get(market.tokens[1]);
+            if (!baseToken || !quoteToken)
+                return;
+            const assetId = 10000 + market.index;
+            const baseQuoteKey = `${baseToken.name}/${quoteToken.name}`;
+            this._nameToAssetId.set(baseQuoteKey, assetId);
+            this._nameToSzDecimals.set(baseQuoteKey, baseToken.szDecimals);
+            this._nameToSpotPairId.set(baseQuoteKey, market.name);
+        });
+    }
+    /**
+     * Get asset ID for a coin.
+     * - For Perpetuals, use the coin name (e.g., "BTC").
+     * - For Spot markets, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
+     * - For Builder Dex assets, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
+     *
+     * @example
+     * ```ts
+     * import { HttpTransport } from "@nktkas/hyperliquid";
+     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+     *
+     * const transport = new HttpTransport(); // or `WebSocketTransport`
+     * const converter = await SymbolConverter.create({ transport });
+     *
+     * converter.getAssetId("BTC"); // → 0
+     * converter.getAssetId("HYPE/USDC"); // → 10107
+     * converter.getAssetId("test:ABC"); // → 110000
+     * ```
+     */
+    getAssetId(name) {
+        return this._nameToAssetId.get(name);
+    }
+    /**
+     * Get size decimals for a coin.
+     * - For Perpetuals, use the coin name (e.g., "BTC").
+     * - For Spot markets, use the "BASE/QUOTE" format (e.g., "HYPE/USDC").
+     * - For Builder Dex assets, use the "DEX_NAME:ASSET_NAME" format (e.g., "test:ABC").
+     *
+     * @example
+     * ```ts
+     * import { HttpTransport } from "@nktkas/hyperliquid";
+     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+     *
+     * const transport = new HttpTransport(); // or `WebSocketTransport`
+     * const converter = await SymbolConverter.create({ transport });
+     *
+     * converter.getSzDecimals("BTC"); // → 5
+     * converter.getSzDecimals("HYPE/USDC"); // → 2
+     * converter.getSzDecimals("test:ABC"); // → 0
+     * ```
+     */
+    getSzDecimals(name) {
+        return this._nameToSzDecimals.get(name);
+    }
+    /**
+     * Get spot pair ID for info endpoints and subscriptions (e.g., l2book, trades).
+     *
+     * Accepts spot markets in the "BASE/QUOTE" format (e.g., "HFUN/USDC").
+     *
+     * @example
+     * ```ts
+     * import { HttpTransport } from "@nktkas/hyperliquid";
+     * import { SymbolConverter } from "@nktkas/hyperliquid/utils";
+     *
+     * const transport = new HttpTransport(); // or `WebSocketTransport`
+     * const converter = await SymbolConverter.create({ transport });
+     *
+     * converter.getSpotPairId("HFUN/USDC"); // → "@2"
+     * converter.getSpotPairId("PURR/USDC"); // → "PURR/USDC" (exceptions exist for some pairs)
+     * ```
+     */
+    getSpotPairId(name) {
+        return this._nameToSpotPairId.get(name);
+    }
+}
+exports.SymbolConverter = SymbolConverter;
+//# sourceMappingURL=_symbolConverter.js.map

package/script/utils/_symbolConverter.js.map

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

package/script/utils/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/utils/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC"}

package/script/utils/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../src/utils/mod.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;;;;;;;;;;;;;;AAEH,wDAAsC;AACtC,+CAA6B"}

package/src/_base.ts

@@ -0,0 +1,31 @@
+import * as v from "valibot";
+
+/** Base error class for all SDK errors. */
+export class HyperliquidError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "HyperliquidError";
+  }
+}
+
+/** Thrown when request parameters fail schema validation. */
+export class ValidationError extends HyperliquidError {
+  override cause: v.ValiError<v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>>;
+  constructor(message: string, options: { cause: v.ValiError<v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>> }) {
+    super(message);
+    this.name = "ValidationError";
+    this.cause = options.cause;
+  }
+}
+
+/** Wrapper around `v.parse` that throws {@linkcode ValidationError} instead of `ValiError`. */
+export function parse<
+  const TSchema extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>,
+>(schema: TSchema, input: unknown): v.InferOutput<TSchema> {
+  try {
+    return v.parse(schema, input);
+  } catch (error) {
+    const valiError = error as v.ValiError<typeof schema>;
+    throw new ValidationError(v.summarize(valiError.issues), { cause: valiError });
+  }
+}

package/src/api/_schemas.ts

@@ -0,0 +1,115 @@
+// deno-lint-ignore-file valibot-project/require-name-suffix
+
+/**
+ * Common valibot schemas for primitive types used across the API.
+ * @module
+ */
+
+import * as v from "valibot";
+
+// ============================================================
+// Number
+// ============================================================
+
+/** Unsigned decimal number as a string (e.g., "123.45"). */
+export const UnsignedDecimal = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([v.string(), v.number()]),
+    v.toString(),
+    v.string(), // HACK: for correct JSONSchema generation
+    v.transform((value) => formatDecimalString(value)),
+    v.regex(/^[0-9]+(\.[0-9]+)?$/),
+  );
+})();
+export type UnsignedDecimal = v.InferOutput<typeof UnsignedDecimal>;
+
+/** Decimal number as a string, can be negative (e.g., "-123.45"). */
+export const Decimal = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([v.string(), v.number()]),
+    v.toString(),
+    v.string(), // HACK: for correct JSONSchema generation
+    v.transform((value) => formatDecimalString(value)),
+    v.regex(/^-?[0-9]+(\.[0-9]+)?$/),
+  );
+})();
+export type Decimal = v.InferOutput<typeof Decimal>;
+
+/** Safe integer number. */
+export const Integer = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([v.string(), v.number()]),
+    v.toNumber(),
+    v.number(), // HACK: for correct JSONSchema generation
+    v.safeInteger(),
+  );
+})();
+export type Integer = v.InferOutput<typeof Integer>;
+
+/** Unsigned safe integer number (>= 0). */
+export const UnsignedInteger = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.union([v.string(), v.number()]),
+    v.toNumber(),
+    v.number(), // HACK: for correct JSONSchema generation
+    v.safeInteger(),
+    v.minValue(0),
+  );
+})();
+export type UnsignedInteger = v.InferOutput<typeof UnsignedInteger>;
+
+function formatDecimalString(value: string): string {
+  return value
+    // remove leading/trailing whitespace
+    .trim() // "  123.45  " → "123.45"
+    // remove leading zeros
+    .replace(/^(-?)0+(?=\d)/, "$1") // "00123" → "123", "-00.5" → "-0.5"
+    // remove trailing zeros
+    .replace(/\.0*$|(\.\d+?)0+$/, "$1") // "1.2000" → "1.2", "5.0" → "5"
+    // add leading zero if starts with decimal point
+    .replace(/^(-?)\./, "$10.") // ".5" → "0.5", "-.5" → "-0.5"
+    // add "0" if string is empty after trimming
+    .replace(/^-?$/, "0") // "" → "0", "-" → "0"
+    // normalize negative zero
+    .replace(/^-0$/, "0"); // "-0" → "0"
+}
+
+// ============================================================
+// Hex
+// ============================================================
+
+/** Hexadecimal string starting with "0x". */
+export const Hex = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.string(),
+    v.regex(/^0[xX][0-9a-fA-F]+$/),
+    v.transform((value) => value.toLowerCase() as `0x${string}`),
+  );
+})();
+export type Hex = v.InferOutput<typeof Hex>;
+
+/** Ethereum address (42 characters hex string). */
+export const Address = /* @__PURE__ */ (() => {
+  return v.pipe(Hex, v.length(42));
+})();
+export type Address = v.InferOutput<typeof Address>;
+
+/** Client order ID (34 characters hex string). */
+export const Cloid = /* @__PURE__ */ (() => {
+  return v.pipe(Hex, v.length(34));
+})();
+export type Cloid = v.InferOutput<typeof Cloid>;
+
+// ============================================================
+// Other
+// ============================================================
+
+/** Percentage string (e.g., "50%"). */
+export const Percent = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.string(),
+    v.regex(/^[0-9]+(\.[0-9]+)?%$/),
+    v.transform((value) => value as `${string}%`),
+  );
+})();
+export type Percent = v.InferOutput<typeof Percent>;

package/src/api/exchange/_methods/_base/_nonce.ts

@@ -0,0 +1,33 @@
+/**
+ * Nonce manager for generating unique, monotonically increasing nonces.
+ * @module
+ */
+
+/**
+ * Nonce manager for generating unique nonces per wallet address and network.
+ * Uses lazy cleanup: removes entries when Date.now() > lastNonce.
+ */
+class NonceManager {
+  private _map = new Map<string, number>();
+
+  getNonce(key: string): number {
+    const now = Date.now();
+    this._cleanup(now);
+
+    const lastNonce = this._map.get(key) ?? 0;
+    const nonce = now > lastNonce ? now : lastNonce + 1;
+    this._map.set(key, nonce);
+    return nonce;
+  }
+
+  private _cleanup(now: number): void {
+    for (const [key, lastNonce] of this._map) {
+      if (now > lastNonce) {
+        this._map.delete(key);
+      }
+    }
+  }
+}
+
+/** Global nonce manager instance. */
+export const globalNonceManager = /* @__PURE__ */ new NonceManager();

package/src/api/exchange/_methods/_base/_semaphore.ts

@@ -0,0 +1,79 @@
+/**
+ * Per-key semaphore registry for serializing async operations.
+ * @module
+ */
+
+import { Semaphore } from "../../../../deps/jsr.io/@std/async/1.1.1/unstable_semaphore.js";
+
+/**
+ * A reference-counted registry for lazily creating and reusing per-key values.
+ *
+ * @template K Map key type.
+ * @template V Stored value type.
+ */
+class RefCountedRegistry<K, V> {
+  private _map = new Map<K, { value: V; refs: number }>();
+  private _factory: () => V;
+
+  /**
+   * Creates a new registry instance.
+   *
+   * @param factory Factory function used to create a new value when a key is first referenced.
+   */
+  constructor(factory: () => V) {
+    this._factory = factory;
+  }
+
+  /**
+   * Increments the reference count for a key and returns its value.
+   *
+   * If the key is not present, a new value is created via the factory.
+   *
+   * @param key Registry key.
+   * @return The value associated with the key.
+   */
+  ref(key: K): V {
+    let entry = this._map.get(key);
+    if (!entry) {
+      entry = { value: this._factory(), refs: 0 };
+      this._map.set(key, entry);
+    }
+    entry.refs++;
+    return entry.value;
+  }
+
+  /**
+   * Decrements the reference count for a key.
+   *
+   * When the count reaches zero, the entry is removed.
+   *
+   * @param key Registry key.
+   */
+  unref(key: K): void {
+    const entry = this._map.get(key);
+    if (!entry) return;
+    if (--entry.refs === 0) {
+      this._map.delete(key);
+    }
+  }
+}
+
+const semaphores = new RefCountedRegistry(() => new Semaphore(1));
+
+/**
+ * Acquires a lock for the given key, executes the provided async function, and releases the lock.
+ *
+ * @param key The key to lock on.
+ * @param fn The async function to execute while holding the lock.
+ * @return The result of the async function.
+ */
+export async function withLock<K, T>(key: K, fn: () => Promise<T>): Promise<T> {
+  const semaphore = semaphores.ref(key);
+  await semaphore.acquire();
+  try {
+    return await fn();
+  } finally {
+    semaphore.release();
+    semaphores.unref(key);
+  }
+}

package/src/api/exchange/_methods/_base/commonSchemas.ts

@@ -0,0 +1,45 @@
+/**
+ * Common schemas and types shared across Exchange API methods.
+ * @module
+ */
+
+import * as v from "valibot";
+import { Hex } from "../../../_schemas.js";
+
+/** Error response for failed operations. */
+export type ErrorResponse = {
+  /** Error status. */
+  status: "err";
+  /** Error message. */
+  response: string;
+};
+
+/** Successful response without specific data. */
+export type SuccessResponse = {
+  /** Successful status. */
+  status: "ok";
+  /** Response details. */
+  response: {
+    /** Type of response. */
+    type: "default";
+  };
+};
+
+/** ECDSA signature components. */
+export const SignatureSchema = /* @__PURE__ */ (() => {
+  return v.object({
+    /** First 32-byte component. */
+    r: v.pipe(Hex, v.length(66)),
+    /** Second 32-byte component. */
+    s: v.pipe(Hex, v.length(66)),
+    /** Recovery identifier. */
+    v: v.picklist([27, 28]),
+  });
+})();
+export type SignatureSchema = v.InferOutput<typeof SignatureSchema>;
+
+/** HyperLiquid network type. */
+export const HyperliquidChainSchema = /* @__PURE__ */ (() => {
+  return v.picklist(["Mainnet", "Testnet"]);
+})();
+export type HyperliquidChainSchema = v.InferOutput<typeof HyperliquidChainSchema>;

package/src/api/exchange/_methods/_base/errors.ts

@@ -0,0 +1,122 @@
+/**
+ * Error types and utilities for Exchange API responses.
+ * @module
+ */
+
+import { HyperliquidError } from "../../../../_base.js";
+
+// ============================================================
+// Type Utilities
+// ============================================================
+
+// deno-lint-ignore ban-types
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Exclude error variants from response type. */
+export type ExcludeErrorResponse<T> = T extends { status: "err" } ? never // with error status
+  : T extends { response: { data: { statuses: ReadonlyArray<infer S> } } } // with multiple statuses
+    ? Exclude<S, { error: unknown }> extends never ? never
+    : Prettify<
+      Omit<T, "response"> & {
+        response: Prettify<Omit<T["response"], "data"> & { data: { statuses: Array<Exclude<S, { error: unknown }>> } }>;
+      }
+    >
+  : T extends { response: { data: { status: infer S } } } // with single status
+    ? S extends { error: unknown } ? never
+    : Prettify<
+      Omit<T, "response"> & {
+        response: Prettify<Omit<T["response"], "data"> & { data: { status: Exclude<S, { error: unknown }> } }>;
+      }
+    >
+  : T;
+
+// ============================================================
+// Error Classes
+// ============================================================
+
+/** Thrown when Exchange API returns an error response. */
+export class ApiRequestError extends HyperliquidError {
+  readonly response: unknown;
+
+  /**
+   * @param response Raw API response that contains the error
+   */
+  constructor(response: unknown) {
+    const message = extractErrorMessage(response) ||
+      "An unknown error occurred while processing an API request. See `response` for more details.";
+    super(message);
+    this.name = "ApiRequestError";
+    this.response = response;
+  }
+}
+
+// ============================================================
+// Error Detection (Duck Typing)
+// ============================================================
+
+/** Check if value has an error property. */
+function hasError(value: unknown): value is { error: string } {
+  return typeof value === "object" && value !== null &&
+    "error" in value && typeof value.error === "string";
+}
+
+/** Check if response has error status. */
+function hasErrorStatus(response: unknown): response is { status: "err"; response: string } {
+  return typeof response === "object" && response !== null &&
+    "status" in response && response.status === "err";
+}
+
+/** Check if response has statuses array with errors. */
+function hasStatusesWithErrors(response: unknown): boolean {
+  if (typeof response !== "object" || response === null) return false;
+  const r = response as { response?: { data?: { statuses?: unknown[] } } };
+  const statuses = r.response?.data?.statuses;
+  return Array.isArray(statuses) && statuses.some(hasError);
+}
+
+/** Check if response has single status with error. */
+function hasSingleStatusWithError(response: unknown): boolean {
+  if (typeof response !== "object" || response === null) return false;
+  const r = response as { response?: { data?: { status?: unknown } } };
+  return hasError(r.response?.data?.status);
+}
+
+/** Extract error message from response using duck typing. */
+function extractErrorMessage(response: unknown): string | undefined {
+  if (hasErrorStatus(response)) {
+    return response.response;
+  }
+
+  const r = response as { response?: { data?: { statuses?: unknown[]; status?: unknown } } };
+
+  if (Array.isArray(r.response?.data?.statuses)) {
+    const errors = r.response.data.statuses.reduce<string[]>((acc, status, index) => {
+      if (hasError(status)) acc.push(`Order ${index}: ${status.error}`);
+      return acc;
+    }, []);
+    if (errors.length > 0) return errors.join(", ");
+  }
+
+  if (hasError(r.response?.data?.status)) {
+    return r.response.data.status.error;
+  }
+
+  return undefined;
+}
+
+// ============================================================
+// Assertions
+// ============================================================
+
+/**
+ * Assert that response is successful, throw ApiRequestError otherwise.
+ *
+ * @param response Raw API response to validate
+ *
+ * @throws {ApiRequestError} If the response contains an error
+ */
+export function assertSuccessResponse(response: unknown): void {
+  if (hasErrorStatus(response) || hasStatusesWithErrors(response) || hasSingleStatusWithError(response)) {
+    throw new ApiRequestError(response);
+  }
+}