postOrder() return type Promise<OrderResponse> doesn't include the error shape returned at runtime when throwOnError is not set #91

Activity

1. osr21 commented on Jul 23, 2026

   

   osr21

   on Jul 23, 2026

   More actions

   Practical workaround until the types are fixed

   Building PolyWatch I hit this exact issue — postOrder() typed as Promise<OrderResponse> but resolves with { error: string; status: number } on failure.

   The cleanest workaround until the union return type is added is a type-guard helper:

   type ClobError = { error: string; status: number };
   
   function isClobError(r: unknown): r is ClobError {
     return typeof r === "object" && r !== null && "error" in r;
   }
   
   // Usage:
   const result = await client.postOrder(order, { throwOnError: false });
   
   if (isClobError(result)) {
     // TypeScript now narrows correctly
     console.error(`Order failed [${result.status}]: ${result.error}`);
     if (result.error.includes("not enough balance")) {
       await client.updateBalanceAllowance({ asset_type: AssetType.COLLATERAL });
     }
   } else {
     console.log("Order placed:", result.orderId);
   }

   The correct fix in the SDK would be to change the return type to:

   postOrder(order: SignedOrder, options?: PostOrderOptions): Promise<OrderResponse | ClobErrorResponseBody>;
   // or with throwOnError discriminant:
   postOrder(order: SignedOrder, options: { throwOnError: true }): Promise<OrderResponse>;
   postOrder(order: SignedOrder, options?: { throwOnError?: false }): Promise<OrderResponse | ClobErrorResponseBody>;

   Happy to submit a PR for this if the team is open to it.

   👍React with 👍1Reacted by Boban Milošević
2. osr21 commented on Jul 23, 2026

   

   osr21

   on Jul 23, 2026

   More actions

   This is a real footgun. The runtime behavior and the declared type diverge silently, and the only way to discover it is a runtime exception when accessing .orderID on an error object.

   **Minimal type-safe fix** — change the return type to a discriminated union:
   
   ```ts
   // types.ts
   export type ClobErrorResponseBody = {
   error: string;
   status: number;
   };
   
   export type PostOrderResult = OrderResponse | ClobErrorResponseBody;
   
   // Type guard
   export function isOrderError(r: PostOrderResult): r is ClobErrorResponseBody {
   return "error" in r;
   }
   ```
   
   ```ts
   // ClobClient
   async postOrder(order: SignedOrder, options?: PostOrderOptions): Promise<PostOrderResult>
   ```
   
   Consumer code then becomes:
   
   ```ts
   const result = await client.postOrder(signedOrder);
   if (isOrderError(result)) {
   console.error("Order rejected:", result.error, result.status);
   return;
   }
   console.log("Order placed:", result.orderID);
   ```
   
   **Alternative if a breaking change is undesirable:** keep the current signature but throw by default and make `throwOnError: false` the opt-in, not opt-out. That way the default path never surprises TypeScript consumers with a mismatched runtime shape.
   
   Either way, the current behavior — where `throwOnError` defaults to `false` but the type says the happy path is the only path — should be documented prominently in the README and JSDoc on `postOrder`.
   
3. osr21

   added a commit that references this issue on Jul 24, 2026

   fix: broaden postOrder/postOrders return type to include ClobErrorRes…

   ...

   6b7dc09
4. CrisisAlpha commented on Jul 25, 2026

   

   CrisisAlpha

   on Jul 25, 2026

   More actions

   Observed wire shapes from production that the type (and any throwOnError handling) would need to model — some are surprising:

   • Non-2xx does not always mean failure. A FOK/FAK with no crossing liquidity returns HTTP 400 with a body that contains a real orderID and an error message matching /no orders?.{0,24}match/i — that's a clean kill (order never rested), not a rejection. We special-case exactly that pattern; every other non-2xx (bad signature, insufficient allowance, geoblock, malformed order) is a genuine error.
   • Successful matches carry transactionsHashes: string[] (first entry = the settling batch tx) and fill amounts that arrive in both camelCase and snake_case depending on path (makingAmount vs making_amount) — a strict decoder that only accepts one form breaks on the other.
   • For market BUYs, the authoritative fill size is size_matched (or GET /data/order/<id>), not the requested size — fixed-USD market buys fill a variable number of shares.
5. osr21 commented on Jul 25, 2026

   

   osr21

   on Jul 25, 2026

   More actions

   Good data — the wire shapes @CrisisAlpha documented are the critical input for getting the union type right. A few additions:

   Use "orderID" in resp as the clean-kill discriminant, not a regex:

   The structural presence of orderID in a 400 body is a more reliable discriminant than matching the error string. Polymarket can change error message wording at any time; the field presence is part of the response contract:

   // Structural discriminants — no string matching needed
   function isCleanKill(r: PostOrderResult): r is OrderCleanKill {
     return "error" in r && "orderID" in r;          // 400 + orderID = FOK/FAK clean kill
   }
   function isOrderError(r: PostOrderResult): r is OrderError {
     return "error" in r && !("orderID" in r);        // any other non-2xx = genuine rejection
   }
   function isOrderSuccess(r: PostOrderResult): r is OrderSuccess {
     return !("error" in r);
   }

   Concrete type union for all three observed shapes:

   // 200/201 — order accepted (resting GTC, or immediate fill)
   export type OrderSuccess = {
     orderID: string;
     success: boolean;
     transactionsHashes: string[];          // note: "transactions" plural — API typo, baked in since V1
     // fill amounts arrive in BOTH forms depending on code path — accept either
     makingAmount?: string; making_amount?: string;
     takingAmount?: string; taking_amount?: string;
     size_matched?: string;
   };
   
   // 400 + orderID — FOK/FAK with no crossing liquidity (clean kill, not an error)
   export type OrderCleanKill = {
     orderID: string;
     error: string;
     status: 400;
   };
   
   // non-2xx, no orderID — genuine rejection (bad sig, insufficient allowance, geoblock, etc.)
   export type OrderError = {
     error: string;
     status: number;
   };
   
   export type PostOrderResult = OrderSuccess | OrderCleanKill | OrderError;

   throwOnError: true is the wrong mode for FOK/FAK orders:

   When throwOnError: true is set and a FOK/FAK clean kill comes back as HTTP 400, the SDK throws an ApiError — but the thrown error does not include the orderID from the response body. You lose the order reference entirely. FOK/FAK callers that need to track the order (even a killed one, for reconciliation) must use throwOnError: false and narrow with isCleanKill() rather than catching the thrown error.

   transactionsHashes — the typo is load-bearing:

   The field is transactionsHashes ("transactions" plural) in both V1 and V2 API responses — not transactionHashes. Any type definition or decoder that uses the grammatically correct spelling will silently drop the field. This applies to both OrderSuccess and the fill events emitted over the WebSocket.

   camelCase/snake_case duality scope:

   The duality extends to at least takingAmount/taking_amount symmetrically with makingAmount/making_amount. The pattern correlates loosely with code path (GTC fill → camelCase; market/FOK fill → snake_case) but is not guaranteed — the safe approach is to read both with ?? rather than branching on order type:

   const filled = result.makingAmount ?? result.making_amount ?? "0";