Latency Model

Understand how polling and connection lanes work under the hood to optimize your integration.

Understanding how nXus communicates with QuickBooks Desktop helps you write faster integrations. The connection operates in one of three states depending on recent activity.

Connection States

Cold (idle 10+ minutes)

When no requests have been made for 10 or more minutes, the SOAP polling interval slows to every 10 seconds and no QuickBooks COM session is held open. The first request after an idle period must wait for the next poll cycle.

Expected latency: 3-10 seconds for the first request.

Active (within 10 minutes of last job)

After a request completes, the polling interval tightens to every 3 seconds. No COM session is held open between polls, but the faster cycle means your next request is picked up quickly.

Expected latency: Up to 3 seconds for the next request.

Warm (mid-session)

During paginated operations or rapid follow-up requests, the existing COM session stays open. Follow-up requests reuse the open session and skip the poll wait entirely.

Expected latency: ~0.5 seconds end-to-end.

Optimize for warm sessions

Batch related operations together when possible. For example, after listing customers, immediately follow up with related invoice queries while the session is still warm. The SDK auto-paginator naturally keeps the session warm throughout iteration.

Latency Summary

Name	Type	Description
Cold start	3-10s	First request after 10+ minutes of inactivity. Poll interval is 10s.
Active poll	~3s	Follow-up request within 10 minutes. Poll interval is 3s, no COM session held.
Warm follow-up	~0.5s	Request during an active COM session (e.g. pagination in progress).

How Early Cursor Close Helps

When you break out of a pagination loop, the SDK fires an explicit cursor close. This releases the connection lane immediately — meaning your next request can reuse the warm session instead of waiting for a 10-second timeout to free the lane. Without the explicit close, the lane stays occupied until the silent-client timeout expires, and your follow-up request would hit a cold or active poll instead of a warm follow-up.

See Pagination — Early Close for details and code examples.

Advanced Use

Request Timeout Tuning

There are two different timeout knobs:

Your client-side HTTP timeout controls how long your app waits before aborting locally.
The backend QuickBooks wait timeout tells nXus how long it should wait for QuickBooks Desktop to pick up and finish the queued job.

For SDK users, the QuickBooks wait timeout is sent through the X-Nxus-Timeout-Seconds header. Raise it when you’re working with slower company files, longer Web Connector polling intervals, or heavier list/report operations.

When to raise it

Start with the defaults. Raise the backend wait timeout for transaction-heavy endpoints like invoices, bills, and reports when QuickBooks Desktop is slow to respond.

Note: The nXus SDK is pre-configured with optimized timeout windows built specifically for QuickBooks Desktop’s architecture. For most standard integrations, you will not need to configure timeouts at all.

timeoutTuning.ts

typescript

123456789101112

import { NxusClient } from "@nxus/qbd";

const client = new NxusClient({
  apiKey: process.env.NXUS_API_KEY!,
  timeout: 30_000, // local HTTP timeout
});

const page = await client.invoices.list({
  connectionId: "conn_abc123",
  limit: 10,
  serverTimeoutSeconds: 120, // backend QuickBooks wait timeout
});

Bottleneck is QuickBooks, not nXus

nXus adds minimal overhead to the request lifecycle. The latency you observe is dominated by the QuickBooks Desktop COM interface and the SOAP polling cycle. The three-state model is designed to minimize that overhead for active integrations.

Pagination Input Sanitization