feat(python-sdk): introduce LangfuseAuthException for auth_check failures

langfuse/__init__.py

@@ -29,6 +29,7 @@
     LangfuseTool,
 )
 from ._version import __version__
+from ._utils.request import LangfuseAuthException
 from .span_filter import (
     KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES,
     is_default_export_span,
@@ -66,6 +67,7 @@
     "RunnerContext",
     "RegressionError",
     "__version__",
+    "LangfuseAuthException",
     "is_default_export_span",
     "is_langfuse_span",
     "is_genai_span",

langfuse/_client/client.py

@@ -86,6 +86,7 @@
 from langfuse._utils.environment import get_common_release_envs
 from langfuse._utils.parse_error import handle_fern_exception
 from langfuse._utils.prompt_cache import PromptCache
+from langfuse._utils.request import LangfuseAuthException
 from langfuse.api import (
     CreateChatPromptRequest,
     CreateChatPromptType,
@@ -3166,7 +3167,7 @@ def auth_check(self) -> bool:
         """Check if the provided credentials (public and secret key) are valid.
 
         Raises:
-            Exception: If no projects were found for the provided credentials.
+            LangfuseAuthException: If no projects were found for the provided credentials.
 
         Note:
             This method is blocking. It is discouraged to use it in production code.
@@ -3177,7 +3178,7 @@ def auth_check(self) -> bool:
                 f"Auth check successful, found {len(projects.data)} projects"
             )
             if len(projects.data) == 0:
-                raise Exception(
+                raise LangfuseAuthException(
                     "Auth check failed, no project found for the keys provided."
                 )
             return True

langfuse/_utils/request.py

@@ -134,3 +134,25 @@ def __str__(self) -> str:
         errors = ", ".join(str(error) for error in self.errors)
 
         return f"[Langfuse] {errors}"
+
+
+class LangfuseAuthException(Exception):
+    """Raised when Langfuse authentication fails.
+
+    This exception is raised when the provided credentials (public key and
+    secret key) are valid but no projects are accessible with them. Catching
+    this specific exception type allows callers to distinguish authentication
+    failures from other errors and handle them explicitly.
+
+    Example::
+
+        from langfuse import Langfuse, LangfuseAuthException
+
+        try:
+            Langfuse().auth_check()
+        except LangfuseAuthException as e:
+            # Handle auth failure cleanly without masking unrelated bugs
+            logger.warning("Langfuse auth failed: %s", e)
+    """
+
+    pass