OUT-3544: Add retry mechanisms for transient network errors

[SandipBajracharya]

Summary

• Expand withRetry classifier to cover transient 5xx (500/502/503/504), undici network failures (ECONNRESET/ECONNREFUSED/ETIMEDOUT/UND_ERR_CONNECT_TIMEOUT), and AbortSignal.timeout/AbortController rejections. Tune factor: 4, retries: 4 so maxTimeout: 10_000 actually engages on the final attempt (back-off becomes 0.5s/2s/8s/10s ≈ 20.5s across 5 attempts).
• Add AbortSignal.timeout(EXTERNAL_FETCH_TIMEOUT_MS) (default 30s, env-overridable) to every external fetch in fetch.helper.ts and copilotAPI.manualFetch.
• Validate response.ok in fetch helpers; non-2xx now throws a typed HttpFetchError (status, statusText, url, body — JSON-parsed if possible, raw text otherwise) instead of cryptic JSON-parse failures.
• Remove 15 dead if (!res) throw new APIError(... 'no response') guards from intuitAPI.ts (97 LOC) now that helpers throw on non-2xx; route real status through getMessageAndCodeFromError so qb_sync_logs records 503 as 503 instead of 500.
• Update useSettings/useQuickbooks to wrap postFetcher calls in try/catch since helpers now throw.

Worst-case op duration: 5 × 30s + 20.5s ≈ 170s, well within the webhook route's maxDuration = 300.

Test plan

• yarn vitest run --project unit (72/72 passing — adds 19 cases covering 5xx retries, undici/cause network errors, TimeoutError, fetch.helper response.ok and timeout paths)
• yarn lint:check clean (only pre-existing warnings)
• yarn prettier:check clean
• yarn tsc --noEmit clean
• Manual smoke against QBO sandbox: trigger a webhook, point one outbound at an unroutable host to force ECONNREFUSED, confirm 5 attempts in qb_sync_logs over ~20s before final failure
• UI spot-check: product/invoice settings save flow still surfaces error state correctly when the API route returns non-2xx

🤖 Generated with Claude Code

[linear-code]

OUT-3544 Add retry mechanisms for transient network errors

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Building		May 11, 2026 10:28am
quickbooks-sync (dev)	Ready	Preview, Comment	May 11, 2026 10:28am

[greptile-apps]

Greptile Summary

This PR hardens outbound HTTP calls with structured timeout, retry, and error-surfacing logic. It introduces HttpFetchError with body and status fields, adds AbortSignal.timeout to all external fetches, expands the withRetry classifier to cover 5xx and network errors, and guards non-idempotent QBO writes with an idempotent: false mode that restricts retries to 429-only.

• Retry classifier rewrite: isRetryableError replaces the previous 429-only check with a documented two-mode classifier; 5xx and network errors retry for reads, are blocked for writes.
• HttpFetchError class: Replaces silent JSON-parse failures with a typed error carrying status, url, body, and an Intuit-detail-aware message that flows into qb_sync_logs.
• IntuitAPI method unwrapping: Methods that internally call the retry-wrapped customQuery are now exposed as plain .bind(this) entries, eliminating the previously identified double-retry nesting on 5xx and timeout errors.

Confidence Score: 5/5

Safe to merge — the classifier, timeout, and error-typing changes are well-scoped and the write-safety mode correctly blocks 5xx retries on non-idempotent QBO operations.

The three concerns raised in previous rounds (retry nesting on methods that chain through customQuery, AbortError vs TimeoutError distinction, and duplicate writes from 5xx retries) are each concretely addressed. Test coverage directly exercises each mode. No new logic gaps were found.

No files require special attention. The most behaviorally sensitive change — the idempotent:false guard in intuitAPI.ts — is the correct fix for the write-duplication risk and is tested.

Important Files Changed

Filename	Overview
src/app/api/core/utils/withRetry.ts	Expanded from a 429-only classifier to a two-mode (idempotent/strict) retry engine with documented backoff tuning; logic is well-tested and addresses the previously flagged nesting and AbortError concerns.
src/utils/intuitAPI.ts	Correctly switches write-path methods to idempotent:false, unwraps methods that chain through customQuery to eliminate double-retry nesting, and removes 15 now-unreachable null-response guards.
src/helper/fetch.helper.ts	Adds response.ok validation, structured HttpFetchError construction with Intuit/Copilot body parsing, and opt-in AbortSignal.timeout; API surface cleanly extended with FetcherOptions without breaking callers.
src/utils/error.ts	Introduces HttpFetchError class and wires it into getMessageAndCodeFromError so real upstream status codes reach qb_sync_logs; URL-based source inference is correctly noted as a heuristic.
src/utils/copilotAPI.ts	manualFetch now validates response.ok and attaches a 30s timeout signal; consistent with fetch.helper changes though per-call timeout override not exposed here.
src/hook/useSettings.ts	Converts postFetcher result-truthy checks to try/catch, correctly gating SWR cache invalidation on success and showing the confirm button on any thrown error.
src/hook/useQuickbooks.ts	Wraps disconnectAction postFetcher call in try/catch; error is logged but silently swallowed — previously flagged outside-diff comment about surfacing failure to the UI is still unaddressed.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant withRetry
    participant IntuitAPI
    participant fetch.helper
    participant QBO as QuickBooks API

    Note over withRetry: idempotent:true (reads) / idempotent:false (writes)

    Caller->>withRetry: customQuery(query)
    withRetry->>IntuitAPI: _customQuery(query)
    IntuitAPI->>fetch.helper: getFetcher(url, headers)
    fetch.helper->>QBO: GET + AbortSignal.timeout(30s)

    alt 2xx response
        QBO-->>fetch.helper: 200 OK
        fetch.helper-->>Caller: parsed JSON
    else 5xx on read (idempotent:true)
        QBO-->>fetch.helper: 503
        fetch.helper-->>withRetry: throws HttpFetchError(503)
        Note over withRetry: isRetryableError=true, backoff 500ms/2s/8s/10s
        withRetry->>IntuitAPI: retry
    else 5xx on write (idempotent:false)
        QBO-->>fetch.helper: 503
        fetch.helper-->>withRetry: throws HttpFetchError(503)
        Note over withRetry: isRetryableError=false, no retry
        withRetry-->>Caller: throws HttpFetchError(503)
    else 429 (both modes)
        QBO-->>fetch.helper: 429
        fetch.helper-->>withRetry: throws HttpFetchError(429)
        withRetry->>IntuitAPI: retry (429 always retryable)
    end

Loading

_{Reviews (3): Last reviewed commit: "fix(OUT-3544): strict retry classifier f..." | Re-trigger Greptile}

[SandipBajracharya]

@greptileai

[greptile-apps]

Non-idempotent writes retried on 5xx — risk of duplicate financial records

createInvoice, createCustomer, createItem, createPayment, createAccount, and createPurchase are all wrapped with wrapWithRetry. With the expanded retry set now including 500/502/503/504 and network errors, a scenario where QBO processes the write successfully but drops the response (e.g., network failure in the response path, or QBO proxy returns 503 after committing the transaction) will cause the retry to issue the same create request again — producing a duplicate invoice, payment, or customer in QuickBooks. A 429 (previous retry condition) signals the server rejected the request; a 503 does not. This gap is not addressed for write paths.

[SandipBajracharya]

@greptileai

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.