Operação

Limites e idempotência

A regra de ouro: nenhum Pix Out sem chave de idempotência. Nenhum webhook processado sem dedupe por id do evento.

Idempotência de escrita

Envie remoteId único (UUID) em toda operação de escrita: cobrança, Pix Out, devolução, webhook config.
Persistir esse remoteId ANTES de disparar a chamada.
Em timeout / erro de rede: repita a chamada com o mesmo remoteId.

async function safePixOut(input) {
  // 1. Grava a intenção (remoteId + destino + valor) no seu banco
  await db.pixOut.create({ id: input.remoteId, status: "pending", ...input });

  // 2. Chama a API com retry idempotente
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      return await ideacash.request("/integration/v1/pix/transfers", {
        method: "POST",
        body: JSON.stringify({ transaction: input }),
      });
    } catch (err) {
      if (err.status === 409) throw err;            // conflito de negócio — não retry
      if (attempt === 3) throw err;
      await sleep(500 * attempt);                   // backoff simples
    }
  }
}

Idempotência no consumo de webhooks

Dedupe por id do evento. Se você já processou, apenas responda 200.
Processamento em background — a entrega HTTP deve durar poucos ms.

Rate limit e volumetria

Os limites operacionais (RPS por credencial, teto diário de Pix Out, ticket máximo) são definidos por contrato. Peça a matriz vigente ao seu contato comercial.

Backoff em 429/503

Se receber 429 ou 5xx, aplique backoff exponencial com jitter (250ms → 500ms → 1s → …). Nunca faça retry sem backoff — piora o incidente para todos.

Timeouts recomendados

Auth (OAuth2): 5s.
Leitura (GET): 10s.
Escrita (POST/PUT/DELETE): 30s. Nunca aborte antes disso — o Pix pode já ter saído.