Skip to content

Exceptions

All exceptions inherit from PerplexityError, allowing callers to catch the entire family with a single except PerplexityError clause.

perplexity_webui_scraper._internal.exceptions.PerplexityError 

PerplexityError(message: str)

Bases: Exception

Base exception for all Perplexity-related errors.

ATTRIBUTE DESCRIPTION
message

Human-readable error description.
Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
31
32
33
def __init__(self, message: str) -> None:
    self.message = message
    super().__init__(message)

perplexity_webui_scraper._internal.exceptions.HTTPError 

HTTPError(message: str, status_code: int | None = None, url: str | None = None, response_body: str | None = None)

Bases: PerplexityError

Raised when an HTTP request returns an unexpected status code.

ATTRIBUTE DESCRIPTION
status_code

HTTP status code, if available.
url

Request URL, if available.
response_body

First 500 characters of the response body, if available.
Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
45
46
47
48
49
50
51
52
53
54
55
def __init__(
    self,
    message: str,
    status_code: int | None = None,
    url: str | None = None,
    response_body: str | None = None,
) -> None:
    self.status_code = status_code
    self.url = url
    self.response_body = response_body[:500] if response_body and len(response_body) > 500 else response_body
    super().__init__(message)

perplexity_webui_scraper._internal.exceptions.AuthenticationError 

AuthenticationError(message: str | None = None)

Bases: HTTPError

Raised when the session token is invalid or expired (HTTP 403).

Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
64
65
66
67
68
def __init__(self, message: str | None = None) -> None:
    super().__init__(
        message or "Access forbidden (403). Session token invalid or expired.",
        status_code=403,
    )

perplexity_webui_scraper._internal.exceptions.RateLimitError 

RateLimitError(message: str | None = None)

Bases: HTTPError

Raised when the Perplexity rate limit is exceeded (HTTP 429).

Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
74
75
76
77
78
def __init__(self, message: str | None = None) -> None:
    super().__init__(
        message or "Rate limit exceeded (429). Please wait before retrying.",
        status_code=429,
    )

perplexity_webui_scraper._internal.exceptions.FileUploadError 

FileUploadError(file_path: str, reason: str)

Bases: PerplexityError

Raised when a file upload to Perplexity's S3 bucket fails.

ATTRIBUTE DESCRIPTION
file_path

Display name or path of the file that failed to upload.
Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
88
89
90
def __init__(self, file_path: str, reason: str) -> None:
    self.file_path = file_path
    super().__init__(f"Upload failed for '{file_path}': {reason}")

perplexity_webui_scraper._internal.exceptions.FileValidationError 

FileValidationError(file_path: str, reason: str)

Bases: PerplexityError

Raised when a file fails local validation before upload.

ATTRIBUTE DESCRIPTION
file_path

Display name or path of the file that failed validation.
Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
100
101
102
def __init__(self, file_path: str, reason: str) -> None:
    self.file_path = file_path
    super().__init__(f"File validation failed for '{file_path}': {reason}")

perplexity_webui_scraper._internal.exceptions.ResearchClarifyingQuestionsError 

ResearchClarifyingQuestionsError(questions: list[str])

Bases: PerplexityError

Raised when Research mode requires clarifying questions before answering.

Perplexity's Deep Research model may return a RESEARCH_CLARIFYING_QUESTIONS SSE step instead of a final answer when the query is ambiguous. The caller should catch this exception, present the questions to the user, and retry with a more specific query.

ATTRIBUTE DESCRIPTION
questions

List of clarifying question strings extracted from the response.
Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
117
118
119
120
121
122
def __init__(self, questions: list[str]) -> None:
    self.questions = questions
    formatted = "\n".join(f"  - {q}" for q in questions) if questions else "  (none)"
    super().__init__(
        f"Research mode requires clarification:\n{formatted}\nPlease rephrase your query to be more specific."
    )

perplexity_webui_scraper._internal.exceptions.ResponseParsingError 

ResponseParsingError(message: str, raw_data: str | None = None)

Bases: PerplexityError

Raised when the API response cannot be parsed into a known structure.

ATTRIBUTE DESCRIPTION
raw_data

Stringified raw response data for debugging, if available.
Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
132
133
134
def __init__(self, message: str, raw_data: str | None = None) -> None:
    self.raw_data = raw_data
    super().__init__(f"Failed to parse API response: {message}")

perplexity_webui_scraper._internal.exceptions.StreamingError 

StreamingError(message: str)

Bases: PerplexityError

Raised when an error occurs during SSE streaming.

Source code in src/perplexity_webui_scraper/_internal/exceptions.py 
140
141
def __init__(self, message: str) -> None:
    super().__init__(f"Streaming error: {message}")