Edge Cases & Errors

When building on PayStreamer, it's important to understand how the smart contracts handle edge cases around user funds and subscription state, and what to do when a transaction aborts.

Insufficient Funds

The most common edge case: a user's account balance can't cover the next billing cycle.

process_due_payment handles this without aborting the transaction — a single insufficient-balance attempt does not cancel or pause anything by itself:

1. The scheduler triggers process_due_payment because the subscription is due.
2. Balance check: the contract checks account::balance(account) < amount.
3. Graceful failure, not a revert: if the balance is too low, the contract calls record_failed_payment and returns — it does not abort. This matters because an abort would waste the scheduler's gas and could loop; a graceful return lets the scheduler move on and still collect its incentive for the attempt.
4. Three strikes, then pause: record_failed_payment increments the subscription's attempt_count. Only once attempt_count >= 3 does the contract set status = 1 (paused, not cancelled) — subscription.move's record_failed_payment. Each failed attempt emits a PaymentFailed event (payment.move) you can subscribe to via queryPaymentFailedEvents.

Handling on the Frontend

Listen for PaymentFailed events (or poll attempt_count/status on the account) to show the right UI — a warning after 1-2 failures, a "resume after topping up" prompt once paused:

import { queryPaymentFailedEvents } from "@paystreamer/sdk/core";
 
const failures = await queryPaymentFailedEvents(accountId, platformId, "testnet");
if (failures.length > 0) {
  console.log(`${failures.length} failed payment attempt(s) recorded.`);
}

Over-depositing

Depositing more than one billing cycle's worth is fine and common (the SDK's own recommended-deposit calculation in useSubscribe/SetupSubscriptionModal targets several cycles of buffer by default). The excess belongs entirely to the user — the platform can never withdraw more than the tier amount per cycle, and the user can withdraw their own excess at any time via buildWithdrawTx, gated by their AccountCap.

Error Reference

Every Move abort surfaces as a numeric code in the transaction error (e.g. MoveAbort ... abort code: 32769). Sui reports these in decimal; the contracts define them in hex — the table below has both. All codes verified directly against the current contract source, not assumed.

account.move

subscription.move

payment.move

platform.move

policies.move

Self-imposed spending limits a user can set on their own account (per_tx_max, monthly_max, min_balance, frequency_min_ms) — these protect the user, not the platform, and only trigger if the user configured them.