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.

Aug 19, 2026

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 with for 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, with data, nextCursor, prevCursor, hasMore, limit, page, lastPage, and total.
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't 2xx. It carries code (a number), httpStatus, details, and requestId.
  • OmnifoxValidationError — 422. It adds fieldErrors, a map of field to list of messages.
  • OmnifoxRateLimitError — 429. It adds retryAfterSec.
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 the Retry-After header.
  • 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 OmnifoxRateLimitError shows 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_id in your logs: it's what makes it possible to trace a specific call when you ask for support.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp