Paginação, erros e novas tentativas nos SDKs da Omnifox
Como os SDKs de Node e Python percorrem listagens, quais exceções eles lançam e quando repetem a chamada sozinhos.
Veja este passo no vídeo · SDKs oficiais: Node, Python e PHP
Paginação
As listagens da API retornam quatro formatos de resposta diferentes, conforme o endpoint. Os SDKs normalizam tudo isso, então você sempre percorre a mesma coisa.
No Node
list(params)retorna um iterador assíncrono: você percorre comfor await. Ele começa pedindo paginação por cursor e, se o endpoint não implementar, cai sozinho para paginação por página. Tem um teto de segurança de 500 páginas.listPage(params)retorna uma única página, comdata,nextCursor,prevCursor,hasMore,limit,page,lastPageetotal.
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);
Nem todos os recursos têm listPage: pipelines e boards retornam um array direto, e boardItems não tem listagem.
No Python
list() retorna um iterador de modelos já validados. Por padrão usa paginação por página, com 50 itens por página; para usar cursor, é preciso pedir.
# por página (padrão)
for c in client.contacts.list():
print(c.id)
# por cursor
for c in client.contacts.list(pagination="cursor"):
print(c.id)
# limitar o total percorrido
for c in client.contacts.list(max_items=200):
print(c.id)
No Python não existe um equivalente ao listPage().
Erros
No Node
Três classes, todas exportadas pelo pacote:
OmnifoxApiError— qualquer resposta que não seja2xx. Trazcode(número),httpStatus,detailserequestId.OmnifoxValidationError—422. AcrescentafieldErrors, um mapa de campo para lista de mensagens.OmnifoxRateLimitError—429. AcrescentaretryAfterSec.
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);
}
}
Os campos se chamam httpStatus e requestId. Não existem status, statusCode nem body.
No Python
OmnifoxError
└── OmnifoxApiError
├── OmnifoxRateLimitError (429)
└── OmnifoxValidationError (422)
OmnifoxApiError traz code (texto), message, details, http_status e request_id. OmnifoxRateLimitError acrescenta retry_after_sec e OmnifoxValidationError acrescenta 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)
Atenção: os erros de rede do httpx (ConnectError, ReadTimeout, RemoteProtocolError) não são envolvidos. Se as tentativas se esgotarem, a exceção que sai é a do httpx.
Novas tentativas
Os dois SDKs repetem a chamada sozinhos, até três vezes por padrão:
- Diante de
429, respeitando o cabeçalhoRetry-After. - Diante de erros de servidor passageiros (
500,502,503,504). - No Python, além disso, diante de erros de conexão e de leitura.
Você desativa com maxRetries: 0 (Node) ou max_retries=0 (Python).
Uma exceção: o download do PDF de um orçamento não passa pela política de novas tentativas em nenhum dos dois SDKs. Se você precisa de tolerância a falhas ali, repita a chamada por conta própria.
Dicas
- Quando o
OmnifoxRateLimitErroraparece apesar das novas tentativas, o seu volume supera o limite do plano de forma sustentada: reduza a frequência ou suba de plano. - Guarde o
requestId/request_idnos seus logs: é o que permite rastrear uma chamada específica ao pedir suporte.
Artigos relacionados
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.