@imbingox/acex 0.4.0-beta.14 → 0.4.0-beta.15

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @imbingox/acex
 
+## 0.4.0-beta.15
+
+### Minor Changes
+
+- 3f6dcb8: 新增 `AcexError.details.venueError.reason`、订单命令错误的 `details.orderState`，并导出 `isOrderStateUnknown()`，方便调用方用稳定语义区分交易所拒单、限流、余额不足和订单状态未知场景。
+
 ## 0.4.0-beta.14
 
 ### Patch Changes

package/docs/api.md

@@ -918,20 +918,43 @@ type OrderEvent =
 可预期错误统一抛 `AcexError`：
 
 ```ts
-import { AcexError } from "@imbingox/acex";
+import { AcexError, isOrderStateUnknown } from "@imbingox/acex";
 
 try {
-  await client.market.subscribeL1Book({ venue: "binance", symbol: "X/Y:Z" });
+  await client.order.createOrder({
+    accountId: "main-binance",
+    symbol: "BTC/USDT:USDT",
+    side: "buy",
+    type: "limit",
+    price: "101000",
+    amount: "0.01",
+    postOnly: true,
+  });
 } catch (error) {
   if (error instanceof AcexError) {
     console.log(error.code);
     console.log(error.details?.venueError?.code);
+    console.log(error.details?.venueError?.reason);
+    console.log(error.details?.orderState);
     console.log(error.details?.transport?.status);
+    console.log(isOrderStateUnknown(error));
   }
 }
 ```
 
-`details.venueError` 是读取交易所结构化拒绝原因的首选字段；`details.transport` 保存已脱敏的 HTTP / transport 诊断信息；`cause` 保留底层错误链。
+`details.venueError` 是读取交易所结构化拒绝原因的首选字段；`details.venueError.reason` 是 SDK 归一后的稳定原因，原始 `code/message` 会继续保留。`details.orderState` 只在订单命令错误中填写：`not_placed` 表示 SDK 判定订单未落地，`unknown` 表示请求可能已经到达交易所，应由调用方后续查询或对账确认。`details.transport` 保存已脱敏的 HTTP / transport 诊断信息；`cause` 保留底层错误链。
+
+归一错误原因：
+
+| `VenueErrorReason` | 典型含义 |
+|---|---|
+| `insufficient_balance` | 余额或保证金不足 |
+| `would_take` | Post Only / maker-only 订单会吃单而被拒 |
+| `order_not_found` | 订单不存在、已不在可撤订单簿或超过交易所可查询范围 |
+| `filter_violation` | 价格、数量、精度、最小名义金额或订单数量限制不满足 |
+| `rate_limited` | 请求权重、订单频率或账户排队被限流 |
+| `timestamp_out_of_sync` | 请求时间戳或 `recvWindow` 与交易所时间不匹配 |
+| `unknown` | 交易所原始码未归入稳定语义，调用方仍可读取原始 `code/message` |
 
 完整错误码：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.14",
+  "version": "0.4.0-beta.15",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/adapters/binance/error-codes.ts

@@ -0,0 +1,53 @@
+import type { VenueErrorReason } from "../../errors.ts";
+
+const BINANCE_RATE_LIMITED_CODES = new Set([
+  "-1003",
+  "-1008",
+  "-1015",
+  "-5041",
+]);
+const BINANCE_TIMESTAMP_OUT_OF_SYNC_CODES = new Set(["-1021", "-5028"]);
+const BINANCE_ORDER_NOT_FOUND_CODES = new Set(["-2011", "-2013"]);
+const BINANCE_INSUFFICIENT_BALANCE_CODES = new Set(["-2018", "-2019"]);
+const BINANCE_WOULD_TAKE_CODES = new Set(["-5022"]);
+const BINANCE_FILTER_VIOLATION_CODES = new Set([
+  "-4131",
+  "-2025",
+  "-1111",
+  "-4002",
+  "-4004",
+  "-4005",
+  "-4013",
+  "-4014",
+  "-4016",
+  "-4023",
+  "-4024",
+  "-4029",
+  "-4030",
+  "-4164",
+  "-4183",
+  "-4184",
+]);
+
+export function normalizeBinanceErrorCode(code: string): VenueErrorReason {
+  if (BINANCE_RATE_LIMITED_CODES.has(code)) {
+    return "rate_limited";
+  }
+  if (BINANCE_TIMESTAMP_OUT_OF_SYNC_CODES.has(code)) {
+    return "timestamp_out_of_sync";
+  }
+  if (BINANCE_ORDER_NOT_FOUND_CODES.has(code)) {
+    return "order_not_found";
+  }
+  if (BINANCE_INSUFFICIENT_BALANCE_CODES.has(code)) {
+    return "insufficient_balance";
+  }
+  if (BINANCE_WOULD_TAKE_CODES.has(code)) {
+    return "would_take";
+  }
+  if (BINANCE_FILTER_VIOLATION_CODES.has(code)) {
+    return "filter_violation";
+  }
+
+  return "unknown";
+}

package/src/adapters/binance/private-adapter.ts

@@ -33,6 +33,7 @@ import type {
   RawRiskUpdate,
   StreamHandle,
 } from "../types.ts";
+import { normalizeBinanceErrorCode } from "./error-codes.ts";
 import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
 
 type TimerHandle = ReturnType<typeof setInterval>;
@@ -183,7 +184,6 @@ const LISTEN_KEY_KEEPALIVE_RETRY_POLICY: HttpRetryPolicy = {
   idempotent: true,
   maxAttempts: 3,
 };
-const BINANCE_ORDER_NOT_FOUND_CODES = new Set(["-2011", "-2013"]);
 function getBinancePapiHttpMessages(timeoutMs: number): HttpClientMessages {
   return {
     http: ({ status, statusText, url, rawBody }) =>
@@ -628,7 +628,7 @@ function isBinanceOrderNotFound(error: unknown): boolean {
 
   try {
     const parsed = JSON.parse(rawBody) as { code?: unknown };
-    return BINANCE_ORDER_NOT_FOUND_CODES.has(`${parsed.code}`);
+    return normalizeBinanceErrorCode(`${parsed.code}`) === "order_not_found";
   } catch {
     return false;
   }
@@ -676,6 +676,10 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     } = {},
   ) {}
 
+  normalizeVenueErrorCode(code: string) {
+    return normalizeBinanceErrorCode(code);
+  }
+
   async bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/adapters/types.ts

@@ -1,3 +1,4 @@
+import type { VenueErrorReason } from "../errors.ts";
 import type {
   AccountCredentials,
   CreateOrderType,
@@ -233,6 +234,7 @@ export interface PrivateUserDataAdapter {
   readonly notes: string[];
   readonly accountCapabilities: VenueAccountCapabilities;
   readonly orderCapabilities: VenueOrderCapabilities;
+  normalizeVenueErrorCode?(code: string): VenueErrorReason;
   bootstrapAccount(
     credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,

package/src/client/context.ts

@@ -4,6 +4,7 @@ import type {
   RawOpenOrdersSnapshot,
   RawOrderUpdate,
 } from "../adapters/types.ts";
+import type { VenueErrorReason } from "../errors.ts";
 import type {
   AccountCredentials,
   AcexInternalError,
@@ -30,6 +31,10 @@ export interface ClientContext {
   assertStarted(): void;
   getRegisteredAccount(accountId: string): RegisteredAccountRecord;
   getPrivateOrderCapabilities(venue: Venue): VenueOrderCapabilities | undefined;
+  normalizeVenueErrorCode(
+    venue: Venue,
+    code: string,
+  ): VenueErrorReason | undefined;
   ensurePrivateCredentials(accountId: string): void;
   subscribePrivateAccountFeed(accountId: string): Promise<void>;
   unsubscribePrivateAccountFeed(accountId: string): void;

package/src/client/runtime.ts

@@ -13,6 +13,7 @@ import {
   AcexError,
   type AcexErrorCode,
   buildAcexErrorDetails,
+  type VenueErrorReason,
 } from "../errors.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
@@ -312,6 +313,13 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     return this.privateAdapters.get(venue)?.orderCapabilities;
   }
 
+  normalizeVenueErrorCode(
+    venue: Venue,
+    code: string,
+  ): VenueErrorReason | undefined {
+    return this.privateAdapters.get(venue)?.normalizeVenueErrorCode?.(code);
+  }
+
   ensurePrivateCredentials(accountId: string): void {
     const account = this.getRegisteredAccount(accountId);
     if (

package/src/errors.ts

@@ -27,9 +27,19 @@ export type AcexErrorTransportKind =
   | "rate_limited"
   | "parse";
 
+export type VenueErrorReason =
+  | "insufficient_balance"
+  | "would_take"
+  | "order_not_found"
+  | "filter_violation"
+  | "rate_limited"
+  | "timestamp_out_of_sync"
+  | "unknown";
+
 export interface AcexVenueErrorDetails {
   readonly code?: string;
   readonly message?: string;
+  readonly reason?: VenueErrorReason;
 }
 
 export interface AcexErrorTransportDetails {
@@ -49,6 +59,7 @@ export interface AcexErrorDetails {
   readonly symbol?: string;
   readonly venueError?: AcexVenueErrorDetails;
   readonly transport?: AcexErrorTransportDetails;
+  readonly orderState?: "not_placed" | "unknown";
 }
 
 export interface AcexErrorOptions {
@@ -91,6 +102,10 @@ export function buildAcexErrorDetails(
   return hasDetails(details) ? details : undefined;
 }
 
+export function isOrderStateUnknown(error: unknown): boolean {
+  return error instanceof AcexError && error.details?.orderState === "unknown";
+}
+
 export function formatAcexErrorMessage(
   message: string,
   details?: AcexErrorDetails,
@@ -166,7 +181,8 @@ function hasDetails(details: AcexErrorDetails): boolean {
       details.accountId ||
       details.symbol ||
       details.venueError ||
-      details.transport,
+      details.transport ||
+      details.orderState,
   );
 }
 

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
   AcexErrorTransportDetails,
   AcexErrorTransportKind,
   AcexVenueErrorDetails,
+  VenueErrorReason,
 } from "./errors.ts";
-export { AcexError } from "./errors.ts";
+export { AcexError, isOrderStateUnknown } from "./errors.ts";
 export * from "./types/index.ts";

package/src/managers/order-manager.ts

@@ -10,6 +10,7 @@ import type {
   PrivateOrderDataConsumer,
   PrivateSubscriptionState,
 } from "../client/context.ts";
+import type { AcexErrorDetails, AcexErrorTransportKind } from "../errors.ts";
 import {
   AcexError,
   buildAcexErrorDetails,
@@ -74,6 +75,15 @@ import {
   setSnapshot,
 } from "./order/store.ts";
 
+type OrderCommandErrorCode =
+  | "ORDER_CANCEL_ALL_FAILED"
+  | "ORDER_CANCEL_FAILED"
+  | "ORDER_CREATE_FAILED";
+
+type OrderErrorCode = OrderCommandErrorCode | "ORDER_INPUT_INVALID";
+
+type OrderCommandOrderState = NonNullable<AcexErrorDetails["orderState"]>;
+
 export class OrderManagerImpl
   implements
     OrderManager,
@@ -990,12 +1000,7 @@ export class OrderManagerImpl
   }
 
   private createError(
-    code:
-      | "VENUE_NOT_SUPPORTED"
-      | "ORDER_CANCEL_ALL_FAILED"
-      | "ORDER_CANCEL_FAILED"
-      | "ORDER_CREATE_FAILED"
-      | "ORDER_INPUT_INVALID",
+    code: "VENUE_NOT_SUPPORTED" | OrderCommandErrorCode | "ORDER_INPUT_INVALID",
     message: string,
     metadata: {
       accountId: string;
@@ -1003,17 +1008,14 @@ export class OrderManagerImpl
       symbol?: string;
     },
   ): AcexError {
-    const details = buildAcexErrorDetails(metadata);
+    const details = this.buildOrderErrorDetails(code, metadata);
     const error = new AcexError(code, message, { details });
     this.context.publishRuntimeError("order", error, metadata);
     return error;
   }
 
   private wrapCommandError(
-    code:
-      | "ORDER_CANCEL_ALL_FAILED"
-      | "ORDER_CANCEL_FAILED"
-      | "ORDER_CREATE_FAILED",
+    code: OrderCommandErrorCode,
     message: string,
     error: unknown,
     metadata: {
@@ -1031,10 +1033,103 @@ export class OrderManagerImpl
       error instanceof Error ? error : new Error(message),
       metadata,
     );
-    const details = buildAcexErrorDetails(metadata, error);
+    const details = this.buildOrderErrorDetails(code, metadata, error);
     return new AcexError(code, formatAcexErrorMessage(message, details), {
       cause: error,
       details,
     });
   }
+
+  private buildOrderErrorDetails(
+    code: "VENUE_NOT_SUPPORTED" | OrderErrorCode,
+    metadata: {
+      accountId: string;
+      venue: Venue;
+      symbol?: string;
+    },
+    error?: unknown,
+  ): AcexErrorDetails | undefined {
+    const details = buildAcexErrorDetails(metadata, error);
+    if (!details || !isOrderErrorCode(code)) {
+      return details;
+    }
+
+    const detailsWithReason = this.addVenueErrorReason(metadata.venue, details);
+    return {
+      ...detailsWithReason,
+      orderState: getOrderState(code, detailsWithReason),
+    };
+  }
+
+  private addVenueErrorReason(
+    venue: Venue,
+    details: AcexErrorDetails,
+  ): AcexErrorDetails {
+    const venueErrorCode = details.venueError?.code;
+    if (!venueErrorCode) {
+      return details;
+    }
+
+    const reason = this.context.normalizeVenueErrorCode(venue, venueErrorCode);
+    if (!reason) {
+      return details;
+    }
+
+    return {
+      ...details,
+      venueError: {
+        ...details.venueError,
+        reason,
+      },
+    };
+  }
+}
+
+function isOrderErrorCode(
+  code: "VENUE_NOT_SUPPORTED" | OrderErrorCode,
+): code is OrderErrorCode {
+  return (
+    code === "ORDER_INPUT_INVALID" ||
+    code === "ORDER_CREATE_FAILED" ||
+    code === "ORDER_CANCEL_FAILED" ||
+    code === "ORDER_CANCEL_ALL_FAILED"
+  );
+}
+
+function getOrderState(
+  code: OrderErrorCode,
+  details: AcexErrorDetails,
+): OrderCommandOrderState {
+  if (code === "ORDER_INPUT_INVALID") {
+    return "not_placed";
+  }
+
+  const transport = details.transport;
+  if (!transport) {
+    return details.venueError ? "not_placed" : "unknown";
+  }
+
+  if (isUnknownOrderTransportKind(transport.kind)) {
+    return "unknown";
+  }
+  if (transport.kind === "rate_limited") {
+    return "not_placed";
+  }
+  if (transport.status !== undefined && transport.status >= 500) {
+    return "unknown";
+  }
+  if (details.venueError) {
+    return "not_placed";
+  }
+  if (transport.status !== undefined && transport.status < 500) {
+    return "not_placed";
+  }
+
+  return "unknown";
+}
+
+function isUnknownOrderTransportKind(
+  kind: AcexErrorTransportKind | undefined,
+): boolean {
+  return kind === "timeout" || kind === "network" || kind === "parse";
 }