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.
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 confor 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, condata,nextCursor,prevCursor,hasMore,limit,page,lastPageytotal.
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 sea2xx. Traecode(número),httpStatus,detailsyrequestId.OmnifoxValidationError—422. AñadefieldErrors, un mapa de campo a lista de mensajes.OmnifoxRateLimitError—429. AñaderetryAfterSec.
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 encabezadoRetry-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
OmnifoxRateLimitErrorsale 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_iden tus registros: es lo que permite rastrear una llamada concreta al pedir soporte.
Artículos relacionados
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.