fix(api): return structured 4xx for missing provider credentials

Fixes #7628

Author: lorenzozanee

openbb_platform/core/openbb_core/api/app_loader.py

@@ -5,7 +5,11 @@
 from openbb_core.api.exception_handlers import ExceptionHandlers
 from openbb_core.app.model.abstract.error import OpenBBError
 from openbb_core.app.router import RouterLoader
-from openbb_core.provider.utils.errors import EmptyDataError, UnauthorizedError
+from openbb_core.provider.utils.errors import (
+    EmptyDataError,
+    MissingCredentialError,
+    UnauthorizedError,
+)
 from pydantic import ValidationError
 
 
@@ -39,5 +43,8 @@ def add_exception_handlers(app: FastAPI):
         app.exception_handlers[ValidationError] = ExceptionHandlers.validation
         app.exception_handlers[ResponseValidationError] = ExceptionHandlers.validation
         app.exception_handlers[OpenBBError] = ExceptionHandlers.openbb
+        app.exception_handlers[MissingCredentialError] = (
+            ExceptionHandlers.missing_credential
+        )
         app.exception_handlers[EmptyDataError] = ExceptionHandlers.empty_data
         app.exception_handlers[UnauthorizedError] = ExceptionHandlers.unauthorized

openbb_platform/core/openbb_core/api/exception_handlers.py

@@ -11,7 +11,11 @@
 from fastapi.responses import JSONResponse, Response
 from openbb_core.app.model.abstract.error import OpenBBError
 from openbb_core.env import Env
-from openbb_core.provider.utils.errors import EmptyDataError, UnauthorizedError
+from openbb_core.provider.utils.errors import (
+    EmptyDataError,
+    MissingCredentialError,
+    UnauthorizedError,
+)
 from pydantic import ValidationError
 
 logger = logging.getLogger("uvicorn.error")
@@ -119,6 +123,26 @@ async def openbb(_: Request, error: OpenBBError):
             detail=str(error.original),
         )
 
+    @staticmethod
+    async def missing_credential(_: Request, error: MissingCredentialError):
+        """Exception handler for MissingCredentialError.
+
+        A missing provider credential is an expected configuration state, not a
+        server fault. Return a structured non-5xx response so clients (e.g. the
+        Workspace widget validator) can distinguish an unconfigured provider
+        from an internal error.
+        """
+        return await ExceptionHandlers._handle(
+            exception=error,
+            status_code=400,
+            detail={
+                "code": "missing_credentials",
+                "provider": error.provider,
+                "credential": error.credential,
+                "message": error.message,
+            },
+        )
+
     @staticmethod
     async def empty_data(_: Request, error: EmptyDataError):
         """Exception handler for EmptyDataError."""

openbb_platform/core/openbb_core/provider/query_executor.py

@@ -6,6 +6,7 @@
 from openbb_core.provider.abstract.fetcher import Fetcher
 from openbb_core.provider.abstract.provider import Provider
 from openbb_core.provider.registry import Registry, RegistryLoader
+from openbb_core.provider.utils.errors import MissingCredentialError
 from pydantic import SecretStr
 
 
@@ -53,9 +54,15 @@ def filter_credentials(
                     if require_credentials:
                         website = provider.website or ""
                         extra_msg = f" Check {website} to get it." if website else ""
-                        raise OpenBBError(
-                            f"Missing credential '{c}'.{extra_msg} Refer to the documentation for setting provider "
-                            "credentials at https://docs.openbb.co/platform/settings/user_settings/api_keys."
+                        message = (
+                            f"Missing credential '{c}'.{extra_msg} Refer to the"
+                            " documentation for setting provider credentials at"
+                            " https://docs.openbb.co/platform/settings/user_settings/api_keys."
+                        )
+                        raise MissingCredentialError(
+                            provider=provider.name.lower(),
+                            credential=c,
+                            message=message,
                         )
                 else:
                     filtered_credentials[c] = secret

openbb_platform/core/openbb_core/provider/utils/errors.py

@@ -14,6 +14,36 @@ def __init__(
         super().__init__(self.message)
 
 
+class MissingCredentialError(OpenBBError):
+    """Exception raised when a required provider credential is not configured."""
+
+    def __init__(
+        self,
+        provider: str,
+        credential: str,
+        message: str | None = None,
+    ):
+        """Initialize the exception.
+
+        Parameters
+        ----------
+        provider : str
+            Name of the provider, e.g. "eia".
+        credential : str
+            Name of the missing credential, e.g. "eia_api_key".
+        message : str | None
+            Optional human-readable message. Defaults to a standard message.
+        """
+        self.provider = provider
+        self.credential = credential
+        self.message = message or (
+            f"Missing credential '{credential}' for provider '{provider}'. "
+            "Refer to the documentation for setting provider credentials at "
+            "https://docs.openbb.co/platform/settings/user_settings/api_keys."
+        )
+        super().__init__(self.message)
+
+
 class UnauthorizedError(OpenBBError):
     """Exception raised for an unauthorized provider request response."""
 

openbb_platform/core/tests/api/test_exception_handlers.py

@@ -0,0 +1,48 @@
+"""Test API exception handlers."""
+
+import asyncio
+import json
+
+from openbb_core.api.exception_handlers import ExceptionHandlers
+from openbb_core.provider.utils.errors import MissingCredentialError
+
+
+def get_response_detail(response):
+    """Return the JSON response detail."""
+    return json.loads(response.body)["detail"]
+
+
+def test_missing_credential_returns_structured_400():
+    """Return a structured 4xx when a provider credential is missing."""
+    error = MissingCredentialError(provider="eia", credential="eia_api_key")
+
+    response = asyncio.run(ExceptionHandlers.missing_credential(None, error))
+
+    assert response.status_code == 400
+    detail = get_response_detail(response)
+    assert detail["code"] == "missing_credentials"
+    assert detail["provider"] == "eia"
+    assert detail["credential"] == "eia_api_key"
+    assert "eia_api_key" in detail["message"]
+
+
+def test_missing_credential_message_preserved():
+    """Keep the provider-provided message when one is supplied."""
+    error = MissingCredentialError(
+        provider="eia",
+        credential="eia_api_key",
+        message="API_KEY_MISSING -> No api_key was supplied.",
+    )
+
+    response = asyncio.run(ExceptionHandlers.missing_credential(None, error))
+
+    detail = get_response_detail(response)
+    assert detail["message"] == "API_KEY_MISSING -> No api_key was supplied."
+
+
+def test_missing_credential_is_openbb_error():
+    """MissingCredentialError must remain an OpenBBError for backward compatibility."""
+    error = MissingCredentialError(provider="eia", credential="eia_api_key")
+
+    assert isinstance(error, Exception)
+    assert str(error) == error.message

openbb_platform/core/tests/provider/test_query_executor.py

@@ -9,6 +9,7 @@
 from openbb_core.provider.abstract.fetcher import Fetcher
 from openbb_core.provider.abstract.provider import Provider
 from openbb_core.provider.query_executor import QueryExecutor
+from openbb_core.provider.utils.errors import MissingCredentialError
 from pydantic import SecretStr
 
 
@@ -75,9 +76,12 @@ def test_filter_credentials_missing_require(mock_query_executor):
     provider.credentials = ["test_provider_api_key"]
     credentials = {"other_api_key": SecretStr("12345")}
 
-    with pytest.raises(OpenBBError, match="Missing credential"):
+    with pytest.raises(MissingCredentialError) as exc_info:
         mock_query_executor.filter_credentials(credentials, provider, True)
 
+    assert exc_info.value.provider == "test"
+    assert exc_info.value.credential == "test_provider_api_key"
+
 
 def test_filter_credentials_empty_require(mock_query_executor):
     """Test if the proper error is raised when a credential is missing."""
@@ -88,9 +92,12 @@ def test_filter_credentials_empty_require(mock_query_executor):
         "other_api_key": SecretStr("12345"),
     }
 
-    with pytest.raises(OpenBBError, match="Missing credential"):
+    with pytest.raises(MissingCredentialError) as exc_info:
         mock_query_executor.filter_credentials(credentials, provider, True)
 
+    assert exc_info.value.provider == "test"
+    assert exc_info.value.credential == "test_provider_api_key"
+
 
 def test_filter_credentials_missing_dont_require(mock_query_executor):
     """Test if the proper error is raised when a credential is missing."""

openbb_platform/providers/eia/openbb_us_eia/utils/helpers.py

@@ -4,6 +4,7 @@
 
 from async_lru import alru_cache
 from openbb_core.app.model.abstract.error import OpenBBError
+from openbb_core.provider.utils.errors import MissingCredentialError
 
 if TYPE_CHECKING:
     from pandas import ExcelFile
@@ -15,6 +16,12 @@ async def response_callback(response, _):
         res = await response.json()
         code = res.get("error", {}).get("code", "")
         msg = res.get("error", {}).get("message", "An invalid api_key was supplied.")
+        if code == "API_KEY_MISSING":
+            raise MissingCredentialError(
+                provider="eia",
+                credential="eia_api_key",
+                message=f"{code} -> {msg}",
+            )
         raise OpenBBError(f"{code} -> {msg}")
     return await response.json()
 

openbb_platform/providers/eia/tests/test_eia_helpers.py

@@ -0,0 +1,58 @@
+"""Tests for EIA provider helpers."""
+
+import asyncio
+
+import pytest
+from openbb_core.provider.utils.errors import MissingCredentialError
+from openbb_us_eia.utils.helpers import response_callback
+
+
+class MockResponse:
+    """Mock aiohttp response."""
+
+    def __init__(self, status, payload):
+        """Initialize the mock response."""
+        self.status = status
+        self._payload = payload
+
+    async def json(self):
+        """Return the JSON payload."""
+        return self._payload
+
+
+def test_response_callback_missing_api_key_raises_missing_credential():
+    """Raise MissingCredentialError when the EIA API reports API_KEY_MISSING."""
+    response = MockResponse(
+        status=403,
+        payload={
+            "error": {
+                "code": "API_KEY_MISSING",
+                "message": "No api_key was supplied.",
+            }
+        },
+    )
+
+    with pytest.raises(MissingCredentialError) as exc_info:
+        asyncio.run(response_callback(response, None))
+
+    assert exc_info.value.provider == "eia"
+    assert exc_info.value.credential == "eia_api_key"
+
+
+def test_response_callback_other_403_raises_generic_error():
+    """Keep generic OpenBBError for non-missing-key 403 responses."""
+    response = MockResponse(
+        status=403,
+        payload={
+            "error": {
+                "code": "UNAUTHORIZED",
+                "message": "Invalid key.",
+            }
+        },
+    )
+
+    with pytest.raises(Exception) as exc_info:
+        asyncio.run(response_callback(response, None))
+
+    assert not isinstance(exc_info.value, MissingCredentialError)
+    assert "UNAUTHORIZED" in str(exc_info.value)