feat: Add SDKError wrapping to surface actual request URL in API errors

This change catches SDKError exceptions from the Speakeasy SDK and wraps
them with additional context including the actual request URL that was
attempted. This makes debugging API issues (like 404 errors) much easier
by showing exactly which URL was requested.

Functions updated with SDKError wrapping:
- get_workspace
- list_connections
- list_workspaces
- list_sources
- list_destinations
- get_connection

The error context now includes:
- request_url: The actual URL that was requested
- request_method: The HTTP method used
- status_code: The HTTP status code
- response_content_type: The content type of the response
- api_root: The configured API root
- workspace_id/connection_id: Resource identifiers

Co-Authored-By: AJ Steers <aj@airbyte.io>

Author: devin-ai-integration[bot]

airbyte/_util/api_util.py

@@ -20,6 +20,7 @@
 import airbyte_api
 import requests
 from airbyte_api import api, models
+from airbyte_api.errors import SDKError
 
 from airbyte.constants import CLOUD_API_ROOT, CLOUD_CONFIG_API_ROOT, CLOUD_CONFIG_API_ROOT_ENV_VAR
 from airbyte.exceptions import (
@@ -58,6 +59,42 @@ def status_ok(status_code: int) -> bool:
     return status_code >= 200 and status_code < 300  # noqa: PLR2004  # allow inline magic numbers
 
 
+def _get_sdk_error_context(error: SDKError) -> dict[str, Any]:
+    """Extract context information from an SDKError for debugging.
+
+    This helper extracts the actual request URL and other useful debugging
+    information from the Speakeasy SDK's SDKError exception. The SDK stores
+    the raw response object which contains the request details.
+    """
+    context: dict[str, Any] = {
+        "status_code": error.status_code,
+        "error_message": error.message,
+    }
+
+    if error.raw_response is not None:
+        request = error.raw_response.request
+        if request is not None:
+            context["request_url"] = str(request.url)
+            context["request_method"] = request.method
+        context["response_content_type"] = error.raw_response.headers.get("content-type")
+
+    return context
+
+
+def _wrap_sdk_error(error: SDKError, base_context: dict[str, Any] | None = None) -> AirbyteError:
+    """Wrap an SDKError with additional context for debugging.
+
+    This function converts a Speakeasy SDK error into an AirbyteError with
+    full URL context, making it easier to debug API issues like 404 errors.
+    """
+    sdk_context = _get_sdk_error_context(error)
+    merged_context = {**(base_context or {}), **sdk_context}
+    return AirbyteError(
+        message=f"API error occurred: {error.message}",
+        context=merged_context,
+    )
+
+
 def get_config_api_root(api_root: str) -> str:
     """Get the configuration API root from the main API root.
 
@@ -185,11 +222,16 @@ def get_workspace(
         client_secret=client_secret,
         bearer_token=bearer_token,
     )
-    response = airbyte_instance.workspaces.get_workspace(
-        api.GetWorkspaceRequest(
-            workspace_id=workspace_id,
-        ),
-    )
+    base_context = {"workspace_id": workspace_id, "api_root": api_root}
+    try:
+        response = airbyte_instance.workspaces.get_workspace(
+            api.GetWorkspaceRequest(
+                workspace_id=workspace_id,
+            ),
+        )
+    except SDKError as e:
+        raise _wrap_sdk_error(e, base_context) from e
+
     if status_ok(response.status_code) and response.workspace_response:
         return response.workspace_response
 
@@ -232,14 +274,19 @@ def list_connections(
     result: list[models.ConnectionResponse] = []
     has_more = True
     offset, page_size = 0, 100
+    base_context = {"workspace_id": workspace_id, "api_root": api_root}
     while has_more:
-        response = airbyte_instance.connections.list_connections(
-            api.ListConnectionsRequest(
-                workspace_ids=[workspace_id],
-                offset=offset,
-                limit=page_size,
-            ),
-        )
+        try:
+            response = airbyte_instance.connections.list_connections(
+                api.ListConnectionsRequest(
+                    workspace_ids=[workspace_id],
+                    offset=offset,
+                    limit=page_size,
+                ),
+            )
+        except SDKError as e:
+            raise _wrap_sdk_error(e, base_context) from e
+
         has_more = bool(response.connections_response and response.connections_response.next)
         offset += page_size
 
@@ -286,10 +333,17 @@ def list_workspaces(
     result: list[models.WorkspaceResponse] = []
     has_more = True
     offset, page_size = 0, 100
+    base_context = {"workspace_id": workspace_id, "api_root": api_root}
     while has_more:
-        response: api.ListWorkspacesResponse = airbyte_instance.workspaces.list_workspaces(
-            api.ListWorkspacesRequest(workspace_ids=[workspace_id], offset=offset, limit=page_size),
-        )
+        try:
+            response: api.ListWorkspacesResponse = airbyte_instance.workspaces.list_workspaces(
+                api.ListWorkspacesRequest(
+                    workspace_ids=[workspace_id], offset=offset, limit=page_size
+                ),
+            )
+        except SDKError as e:
+            raise _wrap_sdk_error(e, base_context) from e
+
         has_more = bool(response.workspaces_response and response.workspaces_response.next)
         offset += page_size
 
@@ -338,14 +392,19 @@ def list_sources(
     result: list[models.SourceResponse] = []
     has_more = True
     offset, page_size = 0, 100
+    base_context = {"workspace_id": workspace_id, "api_root": api_root}
     while has_more:
-        response: api.ListSourcesResponse = airbyte_instance.sources.list_sources(
-            api.ListSourcesRequest(
-                workspace_ids=[workspace_id],
-                offset=offset,
-                limit=page_size,
-            ),
-        )
+        try:
+            response: api.ListSourcesResponse = airbyte_instance.sources.list_sources(
+                api.ListSourcesRequest(
+                    workspace_ids=[workspace_id],
+                    offset=offset,
+                    limit=page_size,
+                ),
+            )
+        except SDKError as e:
+            raise _wrap_sdk_error(e, base_context) from e
+
         has_more = bool(response.sources_response and response.sources_response.next)
         offset += page_size
 
@@ -389,14 +448,19 @@ def list_destinations(
     result: list[models.DestinationResponse] = []
     has_more = True
     offset, page_size = 0, 100
+    base_context = {"workspace_id": workspace_id, "api_root": api_root}
     while has_more:
-        response = airbyte_instance.destinations.list_destinations(
-            api.ListDestinationsRequest(
-                workspace_ids=[workspace_id],
-                offset=offset,
-                limit=page_size,
-            ),
-        )
+        try:
+            response = airbyte_instance.destinations.list_destinations(
+                api.ListDestinationsRequest(
+                    workspace_ids=[workspace_id],
+                    offset=offset,
+                    limit=page_size,
+                ),
+            )
+        except SDKError as e:
+            raise _wrap_sdk_error(e, base_context) from e
+
         has_more = bool(response.destinations_response and response.destinations_response.next)
         offset += page_size
 
@@ -438,11 +502,20 @@ def get_connection(
         bearer_token=bearer_token,
         api_root=api_root,
     )
-    response = airbyte_instance.connections.get_connection(
-        api.GetConnectionRequest(
-            connection_id=connection_id,
-        ),
-    )
+    base_context = {
+        "workspace_id": workspace_id,
+        "connection_id": connection_id,
+        "api_root": api_root,
+    }
+    try:
+        response = airbyte_instance.connections.get_connection(
+            api.GetConnectionRequest(
+                connection_id=connection_id,
+            ),
+        )
+    except SDKError as e:
+        raise _wrap_sdk_error(e, base_context) from e
+
     if status_ok(response.status_code) and response.connection_response:
         return response.connection_response