Handle failures and retries

catch (err)
├── network failure        → retry, same idempotency_key
├── RateLimitError         → wait `Retry-After`, retry, same key
├── TallyError (internal)  → retry once with idempotency key
├── ValidationError        → fix input, don't retry
├── NotFoundError          → fix the id, don't retry
└── AuthenticationError    → branch on err.code:
    ├── amount_too_large       → ask LLM/user for a smaller amount
    ├── daily_cap_exceeded     → wait, or extend the permission
    ├── recipient_not_allowed  → fix the recipient
    ├── contract_not_allowed   → fix the contract
    ├── permission_expired     → re-grant the permission
    └── (anything else)        → real auth failure — rotate the key

async function payWithRetry(intent: PaymentIntent) {
  const key = `${intent.invoice_id}-${intent.attempt}`; // deterministic

  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      return await tally.payments.create({
        agent_id: intent.agent_id,
        wallet: intent.wallet,
        to: intent.to,
        amount_usdc: intent.amount,
        idempotency_key: key,
      });
    } catch (err) {
      if (err instanceof RateLimitError) {
        await sleep(1000 * 2 ** attempt);
        continue;
      }
      if (err instanceof TallyError && err.status >= 500) {
        await sleep(1000 * 2 ** attempt);
        continue;
      }
      throw err; // anything else — let the caller decide
    }
  }
  throw new Error("max retries exceeded");
}

import { AuthenticationError } from "@tallyforagents/sdk";

try {
  await tally.payments.create({ ... });
} catch (err) {
  if (!(err instanceof AuthenticationError)) throw err;

  switch (err.code) {
    case "amount_too_large":
      // The per-tx max is lower than this request. Smaller amounts may work.
      return retryWithSmallerAmount(err);
    case "daily_cap_exceeded":
      // Wait until the rolling 24h window opens up.
      return scheduleForLater(err);
    case "recipient_not_allowed":
    case "contract_not_allowed":
      // Configuration / wiring bug — the destination isn't in the allowlist.
      logAndAlertOps(err);
      throw err;
    case "permission_expired":
      // The permission's expires_at has passed. User needs to re-grant.
      return promptToReGrant(err);
    default:
      // Real auth failure (invalid key, mode mismatch, etc.)
      logAndAlertOps(err);
      throw err;
  }
}

async function waitForFinal(payment_id: string, timeoutMs = 30_000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    const p = await tally.payments.get(payment_id);
    if (p.status !== "pending") return p;
    await new Promise((r) => setTimeout(r, 2_000));
  }
  throw new Error(`Payment ${payment_id} didn't confirm within ${timeoutMs}ms`);
}