feat(perps): retry transient order cancellations

.changeset/dev-535-perps-cancel-retries.md

@@ -0,0 +1,6 @@
+---
+'@polymarket/bindings': minor
+'@polymarket/client': minor
+---
+
+Type known Perps cancellation rejections while preserving unrecognized identifiers, and retry transient `order_in_flight` results with configurable bounded backoff.

packages/bindings/src/perps/orders.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   PerpsAccountFillSchema,
   PerpsCancelOrderResultSchema,
+  PerpsKnownCancelOrderErrorCode,
   PerpsOrderSchema,
   PerpsOrderUpdateSchema,
   PerpsPostOrderAckSchema,
@@ -172,6 +173,41 @@ describe('PerpsCancelOrderResultSchema', () => {
     expect(result.orderId).toBeUndefined();
   });
 
+  it.each(
+    Object.values(PerpsKnownCancelOrderErrorCode),
+  )('types the %s rejection identifier', (error) => {
+    const result = PerpsCancelOrderResultSchema.parse({ error, status: 'err' });
+
+    expect(result).toEqual({
+      clientOrderId: undefined,
+      error,
+      orderId: undefined,
+      status: 'err',
+    });
+  });
+
+  it('preserves cancellation rejection identifiers introduced after release', () => {
+    const result = PerpsCancelOrderResultSchema.parse({
+      error: 'unknown_error_code_18',
+      oid: 123,
+      status: 'err',
+    });
+
+    expect(result).toEqual({
+      clientOrderId: undefined,
+      error: 'unknown_error_code_18',
+      orderId: 123,
+      status: 'err',
+    });
+  });
+
+  it.each([
+    { status: 'err' },
+    { error: '', status: 'err' },
+  ])('rejects a cancellation rejection without an identifier: %j', (value) => {
+    expect(() => PerpsCancelOrderResultSchema.parse(value)).toThrow();
+  });
+
   it('normalizes TP/SL metadata', () => {
     const order = PerpsOrderSchema.parse({
       order_id: 123,

packages/bindings/src/perps/orders.ts

@@ -85,6 +85,43 @@ export const PerpsOrderStatusSchema = z.enum(PerpsOrderStatus);
  */
 export const PerpsCommandStatusSchema = z.enum(['ok', 'err']);
 
+/**
+ * Known rejection identifiers returned when a Perps order cancellation fails.
+ *
+ * The service evolves this set independently of released clients, so
+ * cancellation parsing accepts unknown identifiers as plain strings; see
+ * {@link PerpsCancelOrderErrorCode}.
+ *
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export enum PerpsKnownCancelOrderErrorCode {
+  OrderUnknown = 'order_unknown',
+  OrderNotInOrderbook = 'order_not_in_orderbook',
+  OrderInFlight = 'order_in_flight',
+  OrderNotPendingEngine = 'order_not_pending_engine',
+  OrderNotFound = 'order_not_found',
+}
+
+/**
+ * A Perps order cancellation rejection identifier. Known identifiers are
+ * enumerated in {@link PerpsKnownCancelOrderErrorCode}; newly introduced
+ * identifiers flow through as plain strings so they can be handled before a
+ * client release that enumerates them.
+ *
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export type PerpsCancelOrderErrorCode =
+  | PerpsKnownCancelOrderErrorCode
+  | (string & {});
+
+/**
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export const PerpsCancelOrderErrorCodeSchema = z
+  .string()
+  .min(1)
+  .transform((value): PerpsCancelOrderErrorCode => value);
+
 const PerpsAckErrorSchema = z
   .string()
   .min(1)
@@ -150,17 +187,24 @@ export type PerpsPostOrderAck = z.infer<typeof PerpsPostOrderAckSchema>;
  * @experimental This API may change in a breaking way in any release, including patch releases.
  */
 export const PerpsCancelOrderResultSchema = z
-  .object({
-    status: PerpsCommandStatusSchema,
-    oid: PerpsOrderIdSchema.optional(),
-    coid: PerpsClientOrderIdSchema.optional(),
-    error: z.string().optional(),
-  })
+  .discriminatedUnion('status', [
+    z.object({
+      status: z.literal('ok'),
+      oid: PerpsOrderIdSchema.optional(),
+      coid: PerpsClientOrderIdSchema.optional(),
+    }),
+    z.object({
+      status: z.literal('err'),
+      error: PerpsCancelOrderErrorCodeSchema,
+      oid: PerpsOrderIdSchema.optional(),
+      coid: PerpsClientOrderIdSchema.optional(),
+    }),
+  ])
   .transform((ack) => {
     if (ack.status === 'err') {
       return {
         status: 'err' as const,
-        error: perpsAckError(ack.error),
+        error: ack.error,
         orderId: ack.oid,
         clientOrderId: ack.coid,
       };

packages/client/src/actions/perps.test-d.ts

@@ -21,6 +21,10 @@ import type {
   ListPerpsTradesRequest,
   ListPerpsWithdrawalsRequest,
   OpenPerpsSessionRequest,
+  PerpsCancelOptions,
+  PerpsCancelOrderErrorCode,
+  PerpsCancelOrderResult,
+  PerpsCancelRetryOptions,
   PerpsSessionAccountError,
   PerpsSessionLifecycleError,
   PerpsSessionTradingError,
@@ -34,7 +38,11 @@ import type {
   UpdatePerpsMarginRequest,
   WithdrawFromPerpsRequest,
 } from '../index';
-import { FetchPerpsTickerError, UpdatePerpsMarginError } from '../index';
+import {
+  FetchPerpsTickerError,
+  PerpsKnownCancelOrderErrorCode,
+  UpdatePerpsMarginError,
+} from '../index';
 import type { FetchPerpsInstrumentsRequest } from './perps';
 
 describe('FetchPerpsInstrumentsRequest', () => {
@@ -89,6 +97,8 @@ describe('public Perps exports', () => {
       CancelAllPerpsOrdersRequest,
       CancelPerpsOrderRequest,
       CancelPerpsOrdersRequest,
+      PerpsCancelOptions,
+      PerpsCancelRetryOptions,
       UpdatePerpsLeverageRequest,
       UpdatePerpsMarginRequest,
     ];
@@ -107,4 +117,15 @@ describe('public Perps exports', () => {
     void FetchPerpsTickerError;
     void UpdatePerpsMarginError;
   });
+
+  it('exports known cancel rejections and narrows rejected results', () => {
+    const result = undefined as unknown as PerpsCancelOrderResult;
+
+    if (result.status === 'err') {
+      expectTypeOf(result.error).toEqualTypeOf<PerpsCancelOrderErrorCode>();
+    } else {
+      expectTypeOf(result.error).toEqualTypeOf<undefined>();
+    }
+    void PerpsKnownCancelOrderErrorCode.OrderInFlight;
+  });
 });

packages/client/src/actions/perps.ts

@@ -101,7 +101,9 @@ export type {
   ListPerpsWithdrawalsRequest,
   MarkPerpsNotificationsReadRequest,
   PerpsAutoCancelStatus,
+  PerpsCancelOptions,
   PerpsCancelOrderResult,
+  PerpsCancelRetryOptions,
   PerpsOrderRequest,
   PerpsPlacedTpSlOrder,
   PerpsPlacedTpSlOrders,

packages/client/src/decorators/perps.ts

@@ -71,7 +71,9 @@ export type {
   OpenPerpsSessionRequest,
   PerpsAutoCancelStatus,
   PerpsBookDepth,
+  PerpsCancelOptions,
   PerpsCancelOrderResult,
+  PerpsCancelRetryOptions,
   PerpsOrderRequest,
   PerpsPlacedTpSlOrder,
   PerpsPlacedTpSlOrders,

packages/client/src/errors.ts

@@ -206,6 +206,23 @@ export class TimeoutError extends PolymarketError {
   }
 }
 
+/**
+ * Error thrown when an operation is interrupted through an abort signal.
+ */
+export class OperationAbortedError extends PolymarketError {
+  override name = 'OperationAbortedError' as const;
+
+  constructor(message: string, options: ErrorOptions = {}) {
+    super(message, options);
+  }
+
+  static fromReason(reason: unknown): OperationAbortedError {
+    return new OperationAbortedError('Operation was aborted.', {
+      cause: reason,
+    });
+  }
+}
+
 /**
  * Error thrown when a submitted transaction reaches a terminal failure state.
  */

packages/client/src/index.ts

@@ -13,6 +13,7 @@ export {
   PerpsInstrumentType,
   PerpsInternalTransferDirection,
   PerpsKlineInterval,
+  PerpsKnownCancelOrderErrorCode,
   PerpsKnownWithdrawalStatus,
   PerpsMarginType,
   PerpsNotificationOrderType,