> ## Documentation Index
> Fetch the complete documentation index at: https://tonutils.ness.uz/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Reference of TonConnect exception types and wallet RPC error codes.

All exceptions derive from `TonConnectError` (importable from `ton_connect.exceptions`), which carries `.code` (numeric RPC error code, `0` unless mapped), `.message` (description), and `.info` (extended explanation, or `None`). Errors surface in two ways: as the `error` element of the tuples returned by `wait_connect()` / `wait_transaction()` / `wait_sign_data()` and the `error` argument of [event handlers](/ton-connect/event-handling), or raised directly by methods such as `connect()` and `disconnect()`.

## Connection and Feature Errors

Raised or delivered by the library itself:

| Exception | Description |
| - | - |
| `WalletAlreadyConnectedError` | `connect()` was called while a wallet is already connected. Disconnect first. |
| `WalletNotConnectedError` | `send_transaction()`, `sign_data()`, or `disconnect()` was called while no wallet is connected. |
| `WalletMissingRequiredFeaturesError` | The connected wallet does not declare the minimum required features. Delivered as the `error` of the connect result. |
| `WalletNotSupportFeatureError` | The wallet does not support the requested feature — for example, more messages than its `maxMessages`, extra currencies, or the requested sign-data type. |
| `WalletWrongNetworkError` | The wallet is on a different network than requested. If requested via `connect(network=...)`, delivered as the `error` of the connect result; if via a request's `network`, raised by `send_transaction()` / `sign_data()`. |
| `FetchWalletsError` | `AppWalletsLoader` could not fetch or parse the wallets list. |

`connect()` raises a plain `TonConnectError` when none of the wallet bridges is reachable.

## Wallet Error Codes

Errors reported by the wallet over the bridge are mapped from their RPC code to typed exceptions:

| Code | Exception | Meaning |
| - | - | - |
| 0 | `UnknownError` | An unknown error occurred in the wallet while processing the request. |
| 1 | `BadRequestError` | The request is malformed or contains invalid parameters. |
| 2 | `ManifestNotFoundError` | The wallet could not fetch `tonconnect-manifest.json` at the given `manifest_url`. |
| 3 | `ManifestContentError` | The manifest content is invalid or improperly formatted. |
| 100 | `UnknownAppError` | The app sent an RPC request while not connected to the wallet. |
| 300 | `UserRejectsError` | The user declined the connection or rejected the request in the wallet. |
| 400 | `MethodNotSupportedError` | The wallet does not support the requested RPC method. |
| 500 | `RequestTimeoutError` | The user did not respond within the time limit. Also produced locally when a connect or request timeout expires. |

Unmapped codes produce a plain `TonConnectError` with `.code` set. To map a code yourself, `TonConnectErrors.from_code(code, message)` returns the corresponding typed exception instance.

## Handling Errors

Check the `error` element of the result tuple and branch on the exception type:

```python theme={"theme":{"light":"github-light-default","dark":"dark-plus"}}
from ton_connect.exceptions import RequestTimeoutError, UserRejectsError

request_id = await connector.send_transaction(payload)
result, error = await connector.wait_transaction(request_id)

if error is None:
    print(f"Transaction hash: {result.normalized_hash}")
elif isinstance(error, UserRejectsError):
    print("User rejected the transaction.")
elif isinstance(error, RequestTimeoutError):
    print("User did not respond in time.")
else:
    print(f"Transaction failed [{error.code}]: {error.message}")
```

The same pattern applies to `wait_connect()` and `wait_sign_data()`, and to the `error` argument of event handlers.

<Note>
  Backend verification failures (`VerifyTonProof`, `VerifySignData`, `verify_ton_proof_payload`) raise `nacl.exceptions.BadSignatureError`, not `TonConnectError`. See [Backend Verification](/ton-connect/backend-verification).
</Note>


## Related topics

- [Event Handling](/ton-connect/event-handling.md)
- [Sign Data](/ton-connect/sign-data.md)
- [Send Transaction](/ton-connect/send-transaction.md)
- [Block Scanner](/tools/block-scanner.md)
- [TON Connect](/ton-connect/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.