Merge pull request #28 from code-rabi/fix/flex-query-transient-error-codes

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

Author: NitayRabi

src/flex-query-client.ts

@@ -24,6 +24,21 @@ 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,21 @@ 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
-          statementResponse.error.includes("in progress") ||
-          statementResponse.error.includes("not ready")
-        ) {
-          Logger.log(`[FLEX-QUERY] Statement not ready yet, retrying...`);
+        const code = statementResponse.errorCode ?? "";
+        const normalizedError = statementResponse.error.toLowerCase();
+        const isTransient =
+          FlexQueryClient.TRANSIENT_GET_STATEMENT_ERROR_CODES.has(code) ||
+          normalizedError.includes("in progress") ||
+          normalizedError.includes("not ready") ||
+          normalizedError.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;
       }
@@ -226,4 +246,3 @@ export class FlexQueryClient {
 }
 
 
-

test/flex-query-client.test.ts

@@ -269,6 +269,112 @@ 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 retry when fallback transient message casing differs', 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 transientXml = `<?xml version="1.0" encoding="UTF-8"?>
+<FlexStatementResponse timestamp="26 August, 2023 02:00 PM EDT">
+  <Status>Fail</Status>
+  <ErrorCode>9999</ErrorCode>
+  <ErrorMessage>Statement could not be retrieved. Try Again Shortly.</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 return error when sendRequest fails', async () => {
       const sendResponseXml = `<?xml version="1.0" encoding="UTF-8"?>
 <FlexStatementResponse timestamp="26 August, 2023 01:59 PM EDT">
@@ -375,4 +481,3 @@ describe('FlexQueryClient', () => {
     });
   });
 });
-