Version 0.1.3 · Registry installation commands use exact versions.
API errors, ambiguous payments, and transport failures
Distinguish validation, API, flood-wait, unavailable, malformed-response, and transport errors without exposing credentials.
SDK error categories separate local validation, server API failure, rate limiting, temporary unavailability, malformed JSON/response, and network timeout. Safe error messages do not contain request headers or raw transport exception text.
Check HTTP status and ok together. A syntactically valid JSON response with ok=false is not success even on HTTP 200. API failures may use error, reason, or info; response metadata can contain future fields.
A payment marked unconfirmed or carrying tx_hash must be reconciled, not replayed. The SDK does not invent an order lookup endpoint, guarantee delivery timing, or claim idempotency that the backend lacks.
HTTP 400 with ok=false and unconfirmed=true raises PurchaseOutcomeUnknownError (or the native equivalent), with outcome_unknown=true and safely redacted details including tx_hash. This is not an ordinary validation rejection: funds may already have been sent. Reconcile manually; no automatic purchase retry.
Continue reading
Handle Telegram Stars API 429, Retry-After, and flood wait · Protect wallet credentials in API integrations · Fragment Donor API and SDK FAQ