Paginación, errores y reintentos en los SDKs de Omnifox

Cómo recorren listados los SDKs de Node y Python, qué excepciones lanzan y cuándo reintentan solos.

Aug 19, 2026

Mira este paso en el video · SDK oficiales: Node, Python y PHP

Paginación

Los listados de la API devuelven cuatro formatos de respuesta distintos según el endpoint. Los SDKs los normalizan, así que tú siempre recorres lo mismo.

En Node

  • list(params) devuelve un iterador asíncrono: se recorre con for await. Empieza pidiendo paginación por cursor y, si el endpoint no la implementa, cae solo a paginación por página. Tiene un tope de seguridad de 500 páginas.
  • listPage(params) devuelve una sola página, con data, nextCursor, prevCursor, hasMore, limit, page, lastPage y total.
for await (const c of client.contacts.list({ limit: 100 })) {
  console.log(c.id);
}

const pagina = await client.contacts.listPage({ limit: 50 });
console.log(pagina.data.length, pagina.hasMore);

No todos los recursos tienen listPage: pipelines y boards devuelven un arreglo directo, y boardItems no tiene listado.

En Python

list() devuelve un iterador de modelos ya validados. Por defecto usa paginación por página, con 50 elementos por página; para usar cursor hay que pedirlo.

# por página (por defecto)
for c in client.contacts.list():
    print(c.id)

# por cursor
for c in client.contacts.list(pagination="cursor"):
    print(c.id)

# limitar el total recorrido
for c in client.contacts.list(max_items=200):
    print(c.id)

En Python no existe un equivalente a listPage().

Errores

En Node

Tres clases, todas exportadas por el paquete:

  • OmnifoxApiError — cualquier respuesta que no sea 2xx. Trae code (número), httpStatus, details y requestId.
  • OmnifoxValidationError — 422. Añade fieldErrors, un mapa de campo a lista de mensajes.
  • OmnifoxRateLimitError — 429. Añade 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('Esperar', err.retryAfterSec, 'segundos');
  } else if (err instanceof OmnifoxApiError) {
    console.log(err.code, err.httpStatus, err.requestId, err.message);
  }
}

Los campos se llaman httpStatus y requestId. No existen status, statusCode ni body.

En Python

OmnifoxError
└── OmnifoxApiError
    ├── OmnifoxRateLimitError   (429)
    └── OmnifoxValidationError  (422)

OmnifoxApiError trae code (texto), message, details, http_status y request_id. OmnifoxRateLimitError añade retry_after_sec y OmnifoxValidationError añade 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("reintentar en", e.retry_after_sec, "segundos")
except OmnifoxApiError as e:
    print(e.http_status, e.code, e.message, e.request_id)

Ojo: los errores de red de httpx (ConnectError, ReadTimeout, RemoteProtocolError) no se envuelven. Si agotas los reintentos, la excepción que sale es la de httpx.

Reintentos

Los dos SDKs reintentan solos, hasta tres veces por defecto:

  • Ante 429, respetando el encabezado Retry-After.
  • Ante errores de servidor pasajeros (500, 502, 503, 504).
  • En Python, además, ante errores de conexión y de lectura.

Se desactivan con maxRetries: 0 (Node) o max_retries=0 (Python).

Una excepción: la descarga del PDF de una cotización no pasa por la política de reintentos en ninguno de los dos SDKs. Si necesitas tolerancia a fallos ahí, reintenta tú.

Consejos

  • Cuando OmnifoxRateLimitError sale a pesar de los reintentos, tu volumen supera el límite del plan de forma sostenida: reduce la frecuencia o sube de plan.
  • Guarda el requestId / request_id en tus registros: es lo que permite rastrear una llamada concreta al pedir soporte.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp