fix: retry flex query polling on all transient IB error codes

The polling loop in executeQuery only treated error code 1019 as
"not ready yet", so other transient codes IB returns while a statement
is being prepared (notably 1001 "Statement could not be generated at
this time") were surfaced immediately as terminal errors.

Introduce a TRANSIENT_GET_STATEMENT_ERROR_CODES set covering 1001,
1004-1009, 1018, 1019, and 1021, plus a "try again" substring fallback,
and add regression tests for the transient codes and a guard for
terminal errors (e.g. 1015 invalid token).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NitayRabi

src/flex-query-client.ts

@@ -24,6 +24,21 @@ export interface FlexStatementResponse {
  * API Documentation: https://www.interactivebrokers.com/en/software/am/am/reports/flex_web_service_version_3.htm
  */
 export class FlexQueryClient {
+  // IB Flex Web Service error codes that mean "try again shortly" — the statement
+  // is being prepared. All other Fail codes are terminal (bad token, invalid query, etc.).
+  private static readonly TRANSIENT_GET_STATEMENT_ERROR_CODES = new Set([
+    "1001", // Statement could not be generated at this time
+    "1004", // Statement is incomplete at this time
+    "1005", // Settlement data is not ready
+    "1006", // FIFO P/L data is not ready
+    "1007", // MTM P/L data is not ready
+    "1008", // MTM and FIFO P/L data is not ready
+    "1009", // Server is under heavy load
+    "1018", // Too many requests from this token
+    "1019", // Statement generation in progress
+    "1021", // Statement could not be retrieved at this time
+  ]);
+
   private client: AxiosInstance;
   private token: string;
   // Fixed: gdcdyn → ndcdyn, /Universal/servlet → /AccountManagement/FlexWebService
@@ -182,16 +197,20 @@ export class FlexQueryClient {
       const statementResponse = await this.getStatement(sendResponse.referenceCode);
 
       if (statementResponse.error) {
-        // Check if it's a "not ready yet" error
-        if (
-          statementResponse.errorCode === "1019" || // Statement generation in progress
+        const code = statementResponse.errorCode ?? "";
+        const isTransient =
+          FlexQueryClient.TRANSIENT_GET_STATEMENT_ERROR_CODES.has(code) ||
           statementResponse.error.includes("in progress") ||
-          statementResponse.error.includes("not ready")
-        ) {
-          Logger.log(`[FLEX-QUERY] Statement not ready yet, retrying...`);
+          statementResponse.error.includes("not ready") ||
+          statementResponse.error.includes("try again");
+
+        if (isTransient) {
+          Logger.log(
+            `[FLEX-QUERY] Statement not ready yet (code ${code || "?"}: ${statementResponse.error}), retrying...`
+          );
           continue;
         }
-        
+
         // It's a real error
         return statementResponse;
       }

test/flex-query-client.test.ts

@@ -269,6 +269,77 @@ describe('FlexQueryClient', () => {
       expect(mockGet).toHaveBeenCalledTimes(3);
     });
 
+    it.each([
+      ['1001', 'Statement could not be generated at this time. Please try again shortly.'],
+      ['1009', 'The server is under heavy load and statement could not be generated at this time. Please try again shortly.'],
+      ['1019', 'Statement generation in progress. Please try again shortly.'],
+      ['1021', 'Statement could not be retrieved at this time. Please try again shortly.'],
+    ])('should retry on transient GetStatement error code %s', async (code, message) => {
+      const sendResponseXml = `<?xml version="1.0" encoding="UTF-8"?>
+<FlexStatementResponse timestamp="26 August, 2023 01:59 PM EDT">
+  <Status>Success</Status>
+  <ReferenceCode>${mockReferenceCode}</ReferenceCode>
+</FlexStatementResponse>`;
+
+      const transientXml = `<?xml version="1.0" encoding="UTF-8"?>
+<FlexStatementResponse timestamp="26 August, 2023 02:00 PM EDT">
+  <Status>Fail</Status>
+  <ErrorCode>${code}</ErrorCode>
+  <ErrorMessage>${message}</ErrorMessage>
+</FlexStatementResponse>`;
+
+      const statementXml = `<?xml version="1.0" encoding="UTF-8"?>
+<FlexQueryResponse queryName="Test Query" type="AF">
+  <FlexStatements count="1">
+    <FlexStatement accountId="U12345" />
+  </FlexStatements>
+</FlexQueryResponse>`;
+
+      const mockGet = vi.fn()
+        .mockResolvedValueOnce({ data: sendResponseXml })
+        .mockResolvedValueOnce({ data: transientXml })
+        .mockResolvedValueOnce({ data: statementXml });
+
+      (axios.create as any).mockReturnValue({ get: mockGet });
+      client = new FlexQueryClient({ token: mockToken });
+
+      const result = await client.executeQuery(mockQueryId, 3, 10);
+
+      expect(result).toEqual({ data: statementXml });
+      expect(mockGet).toHaveBeenCalledTimes(3);
+    });
+
+    it('should not retry on terminal GetStatement errors (e.g. 1015 invalid token)', async () => {
+      const sendResponseXml = `<?xml version="1.0" encoding="UTF-8"?>
+<FlexStatementResponse timestamp="26 August, 2023 01:59 PM EDT">
+  <Status>Success</Status>
+  <ReferenceCode>${mockReferenceCode}</ReferenceCode>
+</FlexStatementResponse>`;
+
+      const terminalXml = `<?xml version="1.0" encoding="UTF-8"?>
+<FlexStatementResponse timestamp="26 August, 2023 02:00 PM EDT">
+  <Status>Fail</Status>
+  <ErrorCode>1015</ErrorCode>
+  <ErrorMessage>Token is invalid.</ErrorMessage>
+</FlexStatementResponse>`;
+
+      const mockGet = vi.fn()
+        .mockResolvedValueOnce({ data: sendResponseXml })
+        .mockResolvedValueOnce({ data: terminalXml });
+
+      (axios.create as any).mockReturnValue({ get: mockGet });
+      client = new FlexQueryClient({ token: mockToken });
+
+      const result = await client.executeQuery(mockQueryId, 5, 10);
+
+      expect(result).toEqual({
+        error: 'Token is invalid.',
+        errorCode: '1015',
+      });
+      // Should bail after the first GetStatement attempt — no further retries
+      expect(mockGet).toHaveBeenCalledTimes(2);
+    });
+
     it('should return error when sendRequest fails', async () => {
       const sendResponseXml = `<?xml version="1.0" encoding="UTF-8"?>
 <FlexStatementResponse timestamp="26 August, 2023 01:59 PM EDT">