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.

Aug 19, 2026

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 com for 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, com data, nextCursor, prevCursor, hasMore, limit, page, lastPage e 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);

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 seja 2xx. Traz code (número), httpStatus, details e requestId.
  • OmnifoxValidationError — 422. Acrescenta fieldErrors, um mapa de campo para lista de mensagens.
  • OmnifoxRateLimitError — 429. Acrescenta 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);
  }
}

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çalho Retry-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 OmnifoxRateLimitError aparece 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_id nos seus logs: é o que permite rastrear uma chamada específica ao pedir suporte.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp