Aperant/apps/backend/core/error_utils.py

"""
Shared Error Utilities
======================

Common error detection and classification functions used across
agent sessions, QA, and other modules.
"""

import re


def is_tool_concurrency_error(error: Exception) -> bool:
    """
    Check if an error is a 400 tool concurrency error from Claude API.

    Tool concurrency errors occur when too many tools are used simultaneously
    in a single API request, hitting Claude's concurrent tool use limit.

    Args:
        error: The exception to check

    Returns:
        True if this is a tool concurrency error, False otherwise
    """
    error_str = str(error).lower()
    # Check for 400 status AND tool concurrency keywords
    return "400" in error_str and (
        ("tool" in error_str and "concurrency" in error_str)
        or "too many tools" in error_str
        or "concurrent tool" in error_str
    )


def is_rate_limit_error(error: Exception) -> bool:
    """
    Check if an error is a rate limit error (429 or similar).

    Rate limit errors occur when the API usage quota is exceeded,
    either for session limits or weekly limits.

    Args:
        error: The exception to check

    Returns:
        True if this is a rate limit error, False otherwise
    """
    error_str = str(error).lower()

    # Check for HTTP 429 with word boundaries to avoid false positives
    if re.search(r"\b429\b", error_str):
        return True

    # Check for other rate limit indicators
    return any(
        p in error_str
        for p in [
            "limit reached",
            "rate limit",
            "too many requests",
            "usage limit",
            "quota exceeded",
        ]
    )


def is_authentication_error(error: Exception) -> bool:
    """
    Check if an error is an authentication error (401, token expired, etc.).

    Authentication errors occur when OAuth tokens are invalid, expired,
    or have been revoked (e.g., after token refresh on another process).

    Validation approach:
    - HTTP 401 status code is checked with word boundaries to minimize false positives
    - Additional string patterns are validated against lowercase error messages
    - Patterns are designed to match known Claude API and OAuth error formats

    Known false positive risks:
    - Generic error messages containing "unauthorized" or "access denied" may match
      even if not related to authentication (e.g., file permission errors)
    - Error messages containing these keywords in user-provided content could match
    - Mitigation: HTTP 401 check provides strong signal; string patterns are secondary

    Real-world validation:
    - Pattern matching has been tested against actual Claude API error responses
    - False positive rate is acceptable given the recovery mechanism (prompt user to re-auth)
    - If false positive occurs, user can simply resume without re-authenticating

    Args:
        error: The exception to check

    Returns:
        True if this is an authentication error, False otherwise
    """
    error_str = str(error).lower()

    # Check for HTTP 401 with word boundaries to avoid false positives
    if re.search(r"\b401\b", error_str):
        return True

    # Check for other authentication indicators
    # NOTE: "authentication failed" and "authentication error" are more specific patterns
    # to reduce false positives from generic "authentication" mentions
    return any(
        p in error_str
        for p in [
            "authentication failed",
            "authentication error",
            "unauthorized",
            "invalid token",
            "token expired",
            "authentication_error",
            "invalid_token",
            "token_expired",
            "not authenticated",
            "http 401",
        ]
    )