Error Handling

Every exception ptgc throws is a PtgcException. Catch that for blanket handling, or one of its subtypes to react to a specific failure mode. See Exceptions for the full reference.

The hierarchy

• RpcException — Telegram rejected the request with an error ptgc doesn’t have a more specific type for. Carries code and description mirroring Telegram’s raw error_code/error_message.
• FloodWaitException — you’re being rate-limited. Carries a duration to wait before retrying.
• AuthRequiredException — a method that needs a signed-in session was called before login completed, or the session expired/was revoked server-side.
• TwoFactorRequiredException — checkPassword was called without a pending password challenge from signIn.
• PeerNotFoundException — a username, phone number, or ID couldn’t be resolved to a cached peer.

A general-purpose retry loop

Future<T> withRetry<T>(Future<T> Function() action, {int maxAttempts = 3}) async {
  for (var attempt = 1; ; attempt++) {
    try {
      return await action();
    } on FloodWaitException catch (e) {
      if (attempt >= maxAttempts) rethrow;
      await Future.delayed(e.duration);
    }
  }
}

final result = await withRetry(() => client.members.ban(chatId, userId));

See Handling Flood Waits for a fuller version of this pattern.

Handling an expired session

try {
  await client.chats.listDialogs();
} on AuthRequiredException {
  await client.sessionStore.clear();
  // prompt for auth.sendCode / auth.signIn again
}

See Handling an Expired Session.

Handling an unresolved peer

try {
  await client.members.ban(chatId, userId);
} on PeerNotFoundException {
  // resolve the peer first — Contacts.resolveUsername for users,
  // Members.list for chat members you want to act on
}

See Handling “Peer Not Found”.

Catching everything else

try {
  await client.chats.join(channelId);
} on RpcException catch (e) {
  print('Telegram RPC error ${e.code}: ${e.description}');
} on PtgcException catch (e) {
  print('ptgc error: ${e.message}');
}

See Handling RPC Errors for pattern-matching on specific description values like CHAT_ADMIN_REQUIRED or USER_PRIVACY_RESTRICTED.