Pagination, errors, and retries in the Omnifox SDKs
How the Node and Python SDKs walk through lists, which exceptions they throw, and when they retry on their own.
Watch this step in the video · Official SDKs: Node, Python and PHP
Pagination
API lists return four different response formats depending on the endpoint. The SDKs normalize them, so what you walk is always the same.
In Node
list(params)returns an async iterator: you walk it withfor await. It starts by asking for cursor pagination and, if the endpoint doesn't implement it, falls back to page pagination on its own. It has a safety cap of 500 pages.listPage(params)returns a single page, withdata,nextCursor,prevCursor,hasMore,limit,page,lastPage, andtotal.
for await (const c of client.contacts.list({ limit: 100 })) {
console.log(c.id);
}
const page = await client.contacts.listPage({ limit: 50 });
console.log(page.data.length, page.hasMore);
Not every resource has listPage: pipelines and boards return a plain array, and boardItems has no list method.
In Python
list() returns an iterator of already-validated models. By default it uses page pagination, with 50 items per page; to use a cursor you have to ask for it.
# by page (default)
for c in client.contacts.list():
print(c.id)
# by cursor
for c in client.contacts.list(pagination="cursor"):
print(c.id)
# limit the total walked
for c in client.contacts.list(max_items=200):
print(c.id)
In Python there is no equivalent to listPage().
Errors
In Node
Three classes, all exported by the package:
OmnifoxApiError— any response that isn't2xx. It carriescode(a number),httpStatus,details, andrequestId.OmnifoxValidationError—422. It addsfieldErrors, a map of field to list of messages.OmnifoxRateLimitError—429. It addsretryAfterSec.
import { OmnifoxApiError, OmnifoxRateLimitError, OmnifoxValidationError } from '@omnifox/sdk';
try {
await client.contacts.create({ display_name: 'X', email: '[email protected]' });
} catch (err) {
if (err instanceof OmnifoxValidationError) {
console.log(err.fieldErrors);
} else if (err instanceof OmnifoxRateLimitError) {
console.log('Wait', err.retryAfterSec, 'seconds');
} else if (err instanceof OmnifoxApiError) {
console.log(err.code, err.httpStatus, err.requestId, err.message);
}
}
The fields are called httpStatus and requestId. There is no status, statusCode, or body.
In Python
OmnifoxError
└── OmnifoxApiError
├── OmnifoxRateLimitError (429)
└── OmnifoxValidationError (422)
OmnifoxApiError carries code (a string), message, details, http_status, and request_id. OmnifoxRateLimitError adds retry_after_sec and OmnifoxValidationError adds field_errors.
from omnifox import OmnifoxApiError, OmnifoxRateLimitError, OmnifoxValidationError
try:
client.contacts.create(display_name="x")
except OmnifoxValidationError as e:
print(e.field_errors)
except OmnifoxRateLimitError as e:
print("retry in", e.retry_after_sec, "seconds")
except OmnifoxApiError as e:
print(e.http_status, e.code, e.message, e.request_id)
Watch out: httpx network errors (ConnectError, ReadTimeout, RemoteProtocolError) are not wrapped. If you run out of retries, the exception that comes out is the httpx one.
Retries
Both SDKs retry on their own, up to three times by default:
- On
429, honoring theRetry-Afterheader. - On transient server errors (
500,502,503,504). - In Python, also on connection and read errors.
You disable them with maxRetries: 0 (Node) or max_retries=0 (Python).
One exception: downloading a quote's PDF does not go through the retry policy in either SDK. If you need fault tolerance there, retry it yourself.
Tips
- When
OmnifoxRateLimitErrorshows up despite the retries, your volume is over your plan's limit in a sustained way: lower the frequency or move up a plan. - Save the
requestId/request_idin your logs: it's what makes it possible to trace a specific call when you ask for support.
Related articles
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.