errors

errors

Standardized error codes and messages for the AI Translate application.

get_error_message

get_error_message(code)

Returns the localized message corresponding to an error code.

Source code in src/constants/errors.py

def get_error_message(code: int | None) -> str:
    """Returns the localized message corresponding to an error code."""
    if code is None or code == ERR_NONE:
        return ""
    key = _ERROR_TR_KEYS.get(code)
    if key:
        return tr(key)
    return f"Unknown error (Code: {code})"

map_tag_to_code

map_tag_to_code(msg)

Maps an error tag string to a standardized error code.

PARAMETER	DESCRIPTION
msg	The exception message string (may contain a tag prefix). TYPE: str

RETURNS	DESCRIPTION
int	The corresponding error code, or ERR_UNKNOWN if unrecognized. TYPE: int

Source code in src/constants/errors.py

def map_tag_to_code(msg: str) -> int:
    """Maps an error tag string to a standardized error code.

    Args:
        msg: The exception message string (may contain a tag prefix).

    Returns:
        int: The corresponding error code, or ERR_UNKNOWN if unrecognized.
    """
    for tag, code in _TAG_TO_CODE.items():
        if tag in msg:
            return code
    logger.warning("Unknown error tag '%s' mapped to ERR_UNKNOWN", msg)
    return ERR_UNKNOWN

base_error_tag

base_error_tag(tag)

Returns the base error tag, stripping any :Service suffix.

The engine appends a service-name suffix to AUTH_ERROR raises ("AUTH_ERROR:Gemini" etc.) so the UI can render service-aware messages. Set-membership consumers — fatal-error checks in the PDF / Office image processors, the LLM dispatcher's informative-response filter, etc. — need the BASE tag for their exact-match comparisons; without this strip they'd silently miss every suffixed AUTH_ERROR and demote fatal errors to skip-with- warning.

PARAMETER	DESCRIPTION
tag	The raw tag string, with or without a :Service suffix. TYPE: str

RETURNS	DESCRIPTION
str	The portion of tag before the first colon (or the whole
str	tag if no colon present).

Source code in src/constants/errors.py

def base_error_tag(tag: str) -> str:
    """Returns the base error tag, stripping any ``:Service`` suffix.

    The engine appends a service-name suffix to AUTH_ERROR raises
    (``"AUTH_ERROR:Gemini"`` etc.) so the UI can render service-aware
    messages.  Set-membership consumers — fatal-error checks in the
    PDF / Office image processors, the LLM dispatcher's
    informative-response filter, etc. — need the BASE tag for their
    exact-match comparisons; without this strip they'd silently miss
    every suffixed AUTH_ERROR and demote fatal errors to skip-with-
    warning.

    Args:
        tag: The raw tag string, with or without a ``:Service`` suffix.

    Returns:
        The portion of ``tag`` before the first colon (or the whole
        tag if no colon present).
    """
    return tag.split(":", 1)[0]

_extract_auth_service

_extract_auth_service(raw_msg)

Extracts the service-name suffix from an AUTH_ERROR:Service tag.

Engines that touch a remote auth-required service raise ValueError("AUTH_ERROR:Service Name") to surface WHICH key the user must fix (Google Cloud / Soniox / ElevenLabs / Gemini / a user-named Custom provider). Without the suffix, the user sees "Invalid API key" with no hint which Settings tab to open.

Returns the service name if a suffix is present, otherwise empty string (legacy raises that didn't pass a service). Strips surrounding whitespace so callers can write f"AUTH_ERROR:{name}" without trimming themselves.

Source code in src/constants/errors.py

def _extract_auth_service(raw_msg: str) -> str:
    """Extracts the service-name suffix from an ``AUTH_ERROR:Service`` tag.

    Engines that touch a remote auth-required service raise
    ``ValueError("AUTH_ERROR:Service Name")`` to surface WHICH key the
    user must fix (Google Cloud / Soniox / ElevenLabs / Gemini / a
    user-named Custom provider).  Without the suffix, the user sees
    "Invalid API key" with no hint which Settings tab to open.

    Returns the service name if a suffix is present, otherwise empty
    string (legacy raises that didn't pass a service).  Strips
    surrounding whitespace so callers can write
    ``f"AUTH_ERROR:{name}"`` without trimming themselves.
    """
    # Match ``AUTH_ERROR:`` at the start of the message OR after any
    # leading prefix (an exception chain may stringify as
    # "Error processing: AUTH_ERROR:Google Cloud").  The service name
    # runs to end-of-string or the first newline.
    import re  # noqa: PLC0415

    m = re.search(r"AUTH_ERROR:([^\n]+)", raw_msg)
    if not m:
        return ""
    return m.group(1).strip()

display_error_message

display_error_message(raw_msg)

Converts a raw error tag string to a localized user-friendly message.

Checks against known tag strings (e.g. "MODEL_NOT_FOUND", "AUTH_ERROR") and returns a localized message. If the raw message doesn't match any known tag, it is returned as-is (it may already be localized).

PARAMETER	DESCRIPTION
raw_msg	The raw error message (tag string or already-localized text). TYPE: str

RETURNS	DESCRIPTION
str	A user-friendly, localized error message. TYPE: str

Source code in src/constants/errors.py

def display_error_message(raw_msg: str) -> str:
    """Converts a raw error tag string to a localized user-friendly message.

    Checks against known tag strings (e.g. "MODEL_NOT_FOUND", "AUTH_ERROR")
    and returns a localized message. If the raw message doesn't match any
    known tag, it is returned as-is (it may already be localized).

    Args:
        raw_msg: The raw error message (tag string or already-localized text).

    Returns:
        str: A user-friendly, localized error message.
    """
    if not raw_msg:
        return ""

    # AUTH_ERROR carries an optional ``:Service Name`` suffix so the
    # user sees "Invalid Google Cloud API key" instead of the generic
    # "Invalid API key" — knowing WHICH key is bad is critical when
    # the app has 4 separate auth-required keys (LLM, OCR, TTS, STT).
    # Check this BEFORE the generic substring loop because the
    # service-aware path needs the suffix that the loop would
    # otherwise discard.
    if "AUTH_ERROR" in raw_msg:
        service = _extract_auth_service(raw_msg)
        if service:
            return tr("error_msg.api_key_invalid_for", service=service)
        # No suffix — legacy raise path or a callsite that genuinely
        # doesn't know the service.  Fall through to the generic key.
        return get_error_message(ERR_LLM_API_KEY_INVALID)

    # Check tag → error code → localized message
    for tag, code in _TAG_TO_CODE.items():
        if tag in raw_msg:
            return get_error_message(code)

    # Check tag → direct translation key
    for tag, tr_key in _TAG_TO_TR_KEY.items():
        if tag in raw_msg:
            return tr(tr_key)

    # Not a known tag — return as-is (may already be localized)
    return raw_msg