Error Types - TikTokLive

Overview

TikTokLive provides a comprehensive error hierarchy to help you handle different failure scenarios when connecting to and interacting with TikTok LIVE streams.

Error Hierarchy

All TikTokLive errors inherit from the base TikTokLiveError class:

TikTokLiveError (RuntimeError)
├── AlreadyConnectedError
├── UserOfflineError
├── UserNotFoundError
├── AgeRestrictedError
├── InitialCursorMissingError
├── WebsocketURLMissingError
├── WebcastBlocked200Error
└── SignAPIError
    ├── SignatureRateLimitError
    ├── UnexpectedSignatureError
    ├── SignatureMissingTokensError
    ├── PremiumEndpointError
    └── AuthenticatedWebSocketConnectionError

Base Error

TikTokLiveError

Inherits from: RuntimeError Base error class for all TikTokLive errors. All error messages are automatically prefixed with the package version.

from TikTokLive.client.errors import TikTokLiveError

try:
    # Your code here
    pass
except TikTokLiveError as e:
    print(f"TikTokLive error occurred: {e}")

Connection Errors

AlreadyConnectedError

Inherits from: TikTokLiveError Raised when: Attempting to connect to a user that is already connected to.

from TikTokLive import TikTokLiveClient
from TikTokLive.client.errors import AlreadyConnectedError

client = TikTokLiveClient(unique_id="@username")

try:
    await client.start()
    await client.start()  # This will raise AlreadyConnectedError
except AlreadyConnectedError:
    print("Already connected to this user!")

UserOfflineError

Inherits from: TikTokLiveError Raised when: The requested streamer is offline.

from TikTokLive import TikTokLiveClient
from TikTokLive.client.errors import UserOfflineError

client = TikTokLiveClient(unique_id="@username")

try:
    await client.start()
except UserOfflineError:
    print("This user is not currently live.")

UserNotFoundError

Inherits from: TikTokLiveError Raised when: The user does not have a livestream account (e.g., accounts with less than 1,000 followers). Attributes:

unique_id (str): The unique ID of the user that was not found

from TikTokLive import TikTokLiveClient
from TikTokLive.client.errors import UserNotFoundError

client = TikTokLiveClient(unique_id="@username")

try:
    await client.start()
except UserNotFoundError as e:
    print(f"User '{e.unique_id}' not found or doesn't have LIVE access.")

AgeRestrictedError

Inherits from: TikTokLiveError Raised when: A LIVE stream is age-restricted. Solution: Pass a valid sessionid cookie to bypass age restrictions.

from TikTokLive import TikTokLiveClient
from TikTokLive.client.errors import AgeRestrictedError

client = TikTokLiveClient(unique_id="@username")

try:
    await client.start()
except AgeRestrictedError:
    print("This LIVE is age-restricted. Please provide a sessionid cookie.")
    # Reconnect with sessionid
    client_with_auth = TikTokLiveClient(
        unique_id="@username",
        sessionid="your_session_id_here"
    )
    await client_with_auth.start()

Blocking & Detection Errors

InitialCursorMissingError

Inherits from: TikTokLiveError Raised when: The cursor for connecting to TikTok is missing, indicating that you may be blocked.

from TikTokLive.client.errors import InitialCursorMissingError

try:
    await client.start()
except InitialCursorMissingError:
    print("Connection blocked: Initial cursor missing.")

WebsocketURLMissingError

Inherits from: TikTokLiveError Raised when: The websocket URL to connect to TikTok is missing, indicating that you may be blocked.

from TikTokLive.client.errors import WebsocketURLMissingError

try:
    await client.start()
except WebsocketURLMissingError:
    print("Connection blocked: WebSocket URL missing.")

WebcastBlocked200Error

Inherits from: TikTokLiveError Raised when: The webcast is blocked by TikTok with a 200 status code (detected connection).

from TikTokLive.client.errors import WebcastBlocked200Error

try:
    await client.start()
except WebcastBlocked200Error:
    print("Connection detected and blocked by TikTok.")

Sign API Errors

SignAPIError

Inherits from: TikTokLiveError Raised when: A fetch to the Sign API fails. Attributes:

reason (ErrorReason): The specific reason for the failure
response (httpx.Response | None): The HTTP response object from the Sign API
log_id (str | None): The log ID from the response headers
agent_id (str | None): The agent ID from the response headers

Error Reasons:

RATE_LIMIT: Sign API rate limit exceeded
CONNECT_ERROR: Connection error to Sign API
EMPTY_PAYLOAD: Empty payload received from Sign API
SIGN_NOT_200: Sign API returned non-200 status code
EMPTY_COOKIES: Empty cookies received from Sign API
PREMIUM_ENDPOINT: Premium endpoint access required
AUTHENTICATED_WS: Authenticated WebSocket connection error

from TikTokLive.client.errors import SignAPIError

try:
    await client.start()
except SignAPIError as e:
    print(f"Sign API error: {e.reason.name}")
    if e.response:
        print(f"Log ID: {e.log_id}")
        print(f"Agent ID: {e.agent_id}")

SignatureRateLimitError

Inherits from: SignAPIError Raised when: You hit the Sign API rate limit. Attributes:

retry_after (int): Number of seconds to wait before retrying
reset_time (int): Unix timestamp when the rate limit resets

from TikTokLive.client.errors import SignatureRateLimitError
import asyncio

try:
    await client.start()
except SignatureRateLimitError as e:
    print(f"Rate limited! Retry after {e.retry_after} seconds.")
    print(f"Reset time: {e.reset_time}")
    await asyncio.sleep(e.retry_after)
    await client.start()  # Retry after waiting

UnexpectedSignatureError

Inherits from: SignAPIError Raised when: The Sign API returns an unexpected response (non-200 status code).

from TikTokLive.client.errors import UnexpectedSignatureError

try:
    await client.start()
except UnexpectedSignatureError as e:
    print(f"Unexpected signature response: {e}")

SignatureMissingTokensError

Inherits from: SignAPIError Raised when: The Sign API returns an empty payload (missing tokens).

from TikTokLive.client.errors import SignatureMissingTokensError

try:
    await client.start()
except SignatureMissingTokensError:
    print("Sign API returned empty payload.")

PremiumEndpointError

Inherits from: SignAPIError Raised when: Attempting to access a premium endpoint without proper authorization.

from TikTokLive.client.errors import PremiumEndpointError

try:
    await client.start()
except PremiumEndpointError as e:
    print(f"Premium endpoint access required: {e}")

AuthenticatedWebSocketConnectionError

Inherits from: SignAPIError Raised when: Sending a session ID to the sign server. This is a risky operation that could lead to account bans.

from TikTokLive.client.errors import AuthenticatedWebSocketConnectionError

try:
    await client.start()
except AuthenticatedWebSocketConnectionError:
    print("Authenticated WebSocket connection blocked for security.")

Complete Error Handling Example

from TikTokLive import TikTokLiveClient
from TikTokLive.client.errors import (
    TikTokLiveError,
    AlreadyConnectedError,
    UserOfflineError,
    UserNotFoundError,
    AgeRestrictedError,
    InitialCursorMissingError,
    WebsocketURLMissingError,
    WebcastBlocked200Error,
    SignatureRateLimitError,
    SignAPIError
)
import asyncio

async def connect_to_stream(unique_id: str, sessionid: str = None):
    client = TikTokLiveClient(
        unique_id=unique_id,
        sessionid=sessionid
    )
    
    try:
        await client.start()
        print(f"Successfully connected to @{unique_id}")
        
    except AlreadyConnectedError:
        print("Already connected to this stream.")
        
    except UserOfflineError:
        print(f"@{unique_id} is not currently live.")
        
    except UserNotFoundError as e:
        print(f"User @{e.unique_id} not found or lacks LIVE access.")
        
    except AgeRestrictedError:
        if not sessionid:
            print("Stream is age-restricted. Please provide sessionid.")
            # Retry with authentication
            sessionid = input("Enter your sessionid: ")
            await connect_to_stream(unique_id, sessionid)
        else:
            print("Still age-restricted despite providing sessionid.")
            
    except (InitialCursorMissingError, WebsocketURLMissingError, WebcastBlocked200Error) as e:
        print(f"Connection blocked by TikTok: {type(e).__name__}")
        
    except SignatureRateLimitError as e:
        print(f"Rate limited! Waiting {e.retry_after} seconds...")
        await asyncio.sleep(e.retry_after)
        await connect_to_stream(unique_id, sessionid)
        
    except SignAPIError as e:
        print(f"Sign API error ({e.reason.name}): {e}")
        
    except TikTokLiveError as e:
        print(f"TikTokLive error: {e}")
        
    except Exception as e:
        print(f"Unexpected error: {e}")

# Run the client
await connect_to_stream("username")

Best Practices

Always catch specific errors first: Handle specific error types before catching the base TikTokLiveError.
Respect rate limits: When catching SignatureRateLimitError, always wait for retry_after seconds before retrying.
Handle blocking gracefully: Blocking errors (InitialCursorMissingError, WebsocketURLMissingError, WebcastBlocked200Error) indicate TikTok has detected your connection. Implement exponential backoff or switch to a different connection method.
Use sessionid for age-restricted streams: Always provide a valid sessionid cookie when connecting to age-restricted content.
Log error details: For SignAPIError instances, log the log_id and agent_id for debugging purposes.
Don’t ignore errors: Each error type provides important information about why the connection failed. Use this information to improve your connection strategy.

Documentation Index

​Overview

​Error Hierarchy

​Base Error

​TikTokLiveError

​Connection Errors

​AlreadyConnectedError

​UserOfflineError

​UserNotFoundError

​AgeRestrictedError

​Blocking & Detection Errors

​InitialCursorMissingError

​WebsocketURLMissingError

​WebcastBlocked200Error

​Sign API Errors

​SignAPIError

​SignatureRateLimitError

​UnexpectedSignatureError

​SignatureMissingTokensError

​PremiumEndpointError

​AuthenticatedWebSocketConnectionError

​Complete Error Handling Example

​Best Practices