Exceptions and Limits

Exceptions and Limits

14.0.0 / Reliability

Home / Exceptions and Limits / Examples

---

First rule: distinguish failure from uncertainty

A rejected input, an unpaid prepared invoice, an uncertain broadcast, and a fulfillment timeout are different outcomes.

Warning

Never treat every exception as permission to send another payment. A transaction may have been submitted before the connection failed.

Exception reference

All library exceptions inherit from FragmentError.

Exception	Base	Meaning
ClientError	FragmentError	Client configuration category
ConfigurationError	ClientError	Invalid inputs or unavailable capabilities
CookieError	ClientError	Missing or invalid session cookies
FragmentAPIError	FragmentError	Fragment application failure
FragmentPageError	FragmentAPIError	HTTP/page/hash failure
UserNotFoundError	FragmentAPIError	Recipient resolution failure
ChannelNotFoundError	UserNotFoundError	Channel compatibility specialization
AlreadySubscribedError	FragmentAPIError	Recipient already has Premium
AnonymousNumberError	FragmentAPIError	Number operation failure
PaidMessageLimitError	FragmentAPIError	Recipient minimum Stars requirement
VerificationError	FragmentAPIError	Fragment requires verification
ParseError	FragmentAPIError	Unexpected response or payload format
TransactionError	FragmentAPIError	Preparation or transaction failure
BroadcastUncertainError	TransactionError	Broadcast outcome cannot be established
ConfirmationTimeout	TransactionError	Public compatibility timeout exception
SeqnoError	TransactionError	Public compatibility sequence exception
OperationError	FragmentError	Non-Fragment operation category
WalletError	OperationError	Wallet derivation, balance, or provider failure
SessionStorageError	OperationError	Persistence failure
RetryExhaustedError	OperationError	Opt-in classified retries exhausted
UnexpectedError	OperationError	Public unexpected-error category

ConfigError is an alias for ConfigurationError.

MarketAppAPIError is not part of version 13.

Broadcast uncertainty and recovery

BroadcastUncertainError exposes operation_id and attempted. A blocked duplicate/preflight has attempted=False and points to the earlier recorded operation. A failed provider send has attempted=True. For batches, attempted uncertainty becomes per-item unknown outcomes with the operation id; a blocked preflight still raises.

get_payment(operation_id) returns a PaymentRecord or None; list_payments(sender_address=None) lists records. reconcile_payment(operation_id) reports the original BOC and resumes invoice confirmation without sending another blockchain payment. Use the original Fragment session. Uncorrelated page completion cannot resolve an uncertain invoice.

resolve_payment(operation_id, outcome="settled" | "not_broadcast", evidence=...) records an independently verified operator result. Evidence must be nonempty, and the API does not verify it. settled does not claim fulfillment. not_broadcast requires verified absence AND expiration. Already fulfilled records cannot be reclassified.

asyncio.CancelledError still propagates. Inspect the journal after cancelling a send; do not automatically start another purchase. A journal failure before send prevents broadcast; a failure persisting a returned receipt can leave the pre-send record at sending.

See Payment Batches and Recovery.

Confirmation errors are often returned, not raised

The purchase confirmation path records failures in confirmation_error and returns an unconfirmed receipt.

Do not rely exclusively on catching ConfirmationTimeout.

For a returned purchase result:

1. Record the request and broadcast identifier.
2. Inspect confirmed.
3. Inspect confirmation_error.
4. Reconcile before deciding whether any further payment is appropriate.

Transport behavior

• One reusable Fragment HTTP session per client.
• API hashes are cached by page.
• An explicit Bad request response triggers one hash-refresh retry in the client-owned transport.
• Arbitrary POST network failures are not automatically replayed.
• Authenticated page URLs are restricted to HTTPS fragment.com.
• Redirects are not silently followed by the Fragment transport.
• The raw call method returns application error dictionaries; higher-level methods usually normalize them into exceptions.

The legacy standalone post_fragment_api helper has a separate recovery path. Prefer the client-owned transport for normal integration.

Retry policy

with_retry is opt-in and retries only exceptions accepted by the caller's retry_if function.

Use it for operations you have established to be idempotent. Do not apply a generic retry decorator to purchases, bids, transfers, or withdrawal confirmations.

Input limits

Input	Limit
Stars purchase	50–10,000,000
Premium duration	3, 6, or 12 months
Ads native top-up	1–1,000,000,000 whole TON
Premium giveaway winners	1–24,000
Stars giveaway package	An allowed package between 500 and 1,000,000 total Stars
Stars giveaway winners	1–min(amount // 100, 10_000)
Bid or offer	1–1,000,000,000,000 whole TON
Gateway credits	1–1,000,000,000,000
Gift numeric offset	0–2⁶³−1
Asset type	1, 3, or 5

Strict integer validation rejects booleans, floats, and numeric strings.

Stars giveaway packages

500 · 1,000 · 1,500 · 2,500 · 5,000 · 10,000 · 25,000 · 35,000 · 50,000 · 100,000 · 150,000 · 500,000 · 1,000,000

The package amount is the total, not the per-winner amount.

Wallet limits

Contract	Maximum configured messages
V4R2	4
V5R1	255
HighloadV2	254
HighloadV3R1	64,516
WalletTg	255

Every outgoing message counts, including the separate native fee message.

An invoice or combined batch exceeding the wallet limit is rejected before broadcast rather than split. Batches use one summed native fee message and one configured gas reserve. An ordinary-wallet seqno observation timeout prevents subsequent sends until recovery/operator resolution; sequence advancement is not fulfillment proof.

Timing and balance defaults

Setting	Default
Fragment HTTP timeout	30 seconds
Interactive Telegram authentication deadline	180 seconds
API hash cache lifetime	120 seconds
Purchase confirmation polling interval	2 seconds
Purchase confirmation polling window	60 seconds
Native gas reserve	50,000,000 nanotons / 0.05 TON
Native base unit	1,000,000,000 nanotons per TON

The confirmation window applies to polling. The initial confirmation submission has its own HTTP timing and can add to total elapsed time.

CONFIRMATION_MAX_ATTEMPTS exists as a constant, but the current purchase poller is deadline-based.

Reporting a bug

Include:

• SDK and dependency versions.
• Python version.
• The method and sanitized arguments.
• Exception type or result state.
• Sanitized response structure or HTML fragment.
• Expected and actual parsed values.

Do not include:

• Mnemonics or private keys.
• Cookies or OAuth tokens.
• Login codes.
• Signed BOCs.
• Unredacted private account history.

For a payment issue, do not repeat the payment merely to generate another log.

---

Issue tracker · Error-handling example · Payment lifecycle