:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from typing import Literal
MaxToolErrorType = Literal["validation", "permission", "timeout", "memory_limit", "rate_limited", "api_5xx", "internal"]
class MaxToolError(Exception):
"""
Base exception for MaxTool failures. All errors produce tool messages visible to LLM but not end users.
Error Handling Strategy:
- MaxToolFatalError: Show-stoppers that cannot be recovered from (e.g., permissions, missing config)
- MaxToolTransientError: Intermittent issues that can be retried without changes (e.g., rate limits, timeouts)
- MaxToolRetryableError: Solvable issues that can be fixed with adjusted inputs (e.g., invalid parameters)
- Generic Exception: Unknown failures, treated as fatal (safety net)
When raising these exceptions, provide actionable context about:
- What went wrong
- Why it went wrong (for retryable errors)
- What can be done about it (for retryable errors)
"""
error_type: MaxToolErrorType = "internal"
error_code: str | None = None
def __init__(
self, message: str, *, error_type: MaxToolErrorType | None = None, error_code: str | None = None
) -> None:
"""
Args:
message: Detailed, actionable error message that helps the LLM understand what went wrong
error_code: Machine-readable name of the leaf failure, for analytics. It must hold no caller input.
"""
super().__init__(message)
if error_type is not None:
self.error_type = error_type
if error_code is not None:
self.error_code = error_code
@property
def retry_strategy(self) -> Literal["never", "once", "adjusted"]:
"""
Returns the retry strategy for this error:
- "never": Do not retry (fatal errors)
- "once": Retry once without changes (transient errors)
- "adjusted": Retry with adjusted inputs (solvable errors)
"""
return "never"
@property
def retry_hint(self) -> str:
"""
Returns the retry hint message to append to error messages for the LLM.
"""
retry_hints = {
"never": "",
"once": " You may retry this operation once without changes.",
"adjusted": " You may retry with adjusted inputs.",
}
return retry_hints[self.retry_strategy]
def to_summary(self, max_length: int = 500) -> str:
"""
Create a truncated summary for context management.
Args:
max_length: Maximum length of the error message before truncation
Returns:
Formatted string with exception class name and truncated message
"""
exception_name = self.__class__.__name__
exception_msg = str(self).strip()
if len(exception_msg) > max_length:
exception_msg = exception_msg[:max_length] + "…"
return f"{exception_name}: {exception_msg}"
class MaxToolFatalError(MaxToolError):
"""
Fatal error that cannot be recovered from. Do not retry.
"""
@property
def retry_strategy(self) -> Literal["never", "once", "adjusted"]:
return "never"
class MaxToolTransientError(MaxToolError):
"""
Transient error due to temporary service issues. Can be retried once without changes.
"""
error_type = "api_5xx"
@property
def retry_strategy(self) -> Literal["never", "once", "adjusted"]:
return "once"
class MaxToolRetryableError(MaxToolError):
"""
Solvable error that can be fixed with adjusted inputs. Can be retried with corrections.
"""
error_type = "validation"
@property
def retry_strategy(self) -> Literal["never", "once", "adjusted"]:
return "adjusted"
class MaxToolAccessDeniedError(MaxToolFatalError):
"""
Access denied error when user doesn't have permission to use a tool or access a resource.
This is a fatal error - the user needs to contact their admin to get access.
"""
error_type = "permission"
def __init__(
self,
resource: str,
required_level: str,
action: str = "access",
):
self.resource = resource
self.required_level = required_level
self.action = action
message = f"The user does not have {required_level} access to {action} {resource}s. Suggest the user to contact their project admin to request access."
super().__init__(message)