fix: Tune timeouts on dbt platform httpx clients (#803)

## Summary

- Set explicit timeouts on all `httpx.AsyncClient()` calls that hit dbt
platform APIs
- Timeout values based on production latency data (Datadog spans, last 7
days)
- Tiered by API latency profile rather than one-size-fits-all

## Why

`httpx.AsyncClient()` defaults to a 5-second timeout. For Admin API
calls like `GET /runs/{id}/`, the p99 latency is 5.0s, meaning ~1% of
requests hit the timeout. This caused `ReadTimeout` errors in
production.

**82 errors over the last 14 days, accelerating**: 5-6/day in week 1,
10-17/day in week 2. The last 3 full days (Jun 8-10) accounted for 50%
of all errors.

Top 3 tools by error count: `list_metrics` (22), `get_dimensions` (20),
`get_job_run_error` (19), accounting for 74% of all timeouts. A single
account (46429) produced 46% of all errors.

## Timeout values

| Client | Old timeout | New timeout | Justification |
|---|---|---|---|
| Admin API (`dbt_admin/client.py`) | 5s (default) | **15s** | p99 =
5.0s, max = 5.3s; 15s gives ~3x headroom |
| Discovery API (`discovery/client.py`) | 5s (default) | **15s** | p99 =
3.8s (worst cluster), max = 77s (outlier); 15s covers normal operation |
| Project/env resolvers | 5s (default) | **15s** | Same platform API
endpoints as Admin API |
| Semantic Layer GQL (`gql_request.py`) | 30s | **60s** | Schema
operations reach 38.7s max; 60s gives ~1.5x headroom |

Product docs clients (fetching from external docs sites) retain their
existing explicit timeouts (30s, 120s).

## Test plan

- [x] `ruff check` and `ruff format` pass
- [x] 748 unit tests pass (rebased on latest main)
- [ ] Verify ReadTimeout error rate drops in production after deploy

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: alan-andrade

.changes/unreleased/Bug Fix-20260611-142437.yaml

@@ -0,0 +1,3 @@
+kind: Bug Fix
+body: Set explicit timeouts on all dbt platform httpx clients to prevent ReadTimeout errors (15s for REST APIs, 60s for Semantic Layer GQL)
+time: 2026-06-11T14:24:37.725211+01:00

src/dbt_mcp/config/settings.py

@@ -15,6 +15,8 @@
 logger = logging.getLogger(__name__)
 
 DEFAULT_DBT_CLI_TIMEOUT = 60
+PLATFORM_API_TIMEOUT = 15.0
+SEMANTIC_LAYER_GQL_TIMEOUT = 60.0
 
 
 class DbtMcpLogSettings(BaseSettings):

src/dbt_mcp/dbt_admin/client.py

@@ -7,6 +7,7 @@
 import httpx
 
 from dbt_mcp.config.config_providers import AdminApiConfig, ConfigProvider
+from dbt_mcp.config.settings import PLATFORM_API_TIMEOUT
 from dbt_mcp.errors import (
     AdminAPIError,
     ArtifactRetrievalError,
@@ -43,7 +44,7 @@ async def _make_request(
         headers = await self.get_headers()
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(timeout=PLATFORM_API_TIMEOUT) as client:
                 response = await client.request(
                     method,
                     url,
@@ -394,7 +395,7 @@ async def get_job_run_artifact(
         } | config.headers_provider.get_headers()
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(timeout=PLATFORM_API_TIMEOUT) as client:
                 response = await client.get(
                     f"{config.url}/api/v2/accounts/{account_id}/runs/{run_id}/artifacts/{artifact_path}",
                     headers=get_artifact_header,

src/dbt_mcp/discovery/client.py

@@ -7,6 +7,7 @@
 from pydantic import BaseModel, ConfigDict, Field
 
 from dbt_mcp.config.config_providers import DiscoveryConfig
+from dbt_mcp.config.settings import PLATFORM_API_TIMEOUT
 from dbt_mcp.discovery.graphql import load_query
 from dbt_mcp.errors import InvalidParameterError, ToolCallError
 from dbt_mcp.errors.common import NotFoundError
@@ -362,7 +363,7 @@ async def execute_query(
     url = config.url
     headers = config.headers_provider.get_headers()
 
-    async with httpx.AsyncClient() as client:
+    async with httpx.AsyncClient(timeout=PLATFORM_API_TIMEOUT) as client:
         response = await client.post(
             url=url,
             json={"query": query, "variables": variables},

src/dbt_mcp/project/project_resolver.py

@@ -4,6 +4,7 @@
 
 import httpx
 
+from dbt_mcp.config.settings import PLATFORM_API_TIMEOUT
 from dbt_mcp.oauth.dbt_platform import (
     DbtPlatformAccount,
     DbtPlatformProject,
@@ -18,7 +19,7 @@ async def get_account(
     account_id: int,
     headers: dict[str, str],
 ) -> DbtPlatformAccount:
-    async with httpx.AsyncClient() as client:
+    async with httpx.AsyncClient(timeout=PLATFORM_API_TIMEOUT) as client:
         response = await client.get(
             # Using v2 as this endpoint in v3 was not available in testing
             url=f"{dbt_platform_url}/api/v2/accounts/{account_id}/",
@@ -33,7 +34,7 @@ async def get_all_accounts(
     dbt_platform_url: str,
     headers: dict[str, str],
 ) -> list[DbtPlatformAccount]:
-    async with httpx.AsyncClient() as client:
+    async with httpx.AsyncClient(timeout=PLATFORM_API_TIMEOUT) as client:
         response = await client.get(
             url=f"{dbt_platform_url}/api/v3/accounts/",
             headers=headers,
@@ -53,7 +54,7 @@ async def get_all_projects_for_account(
     """Fetch all projects for an account using offset/page_size pagination."""
     offset = 0
     projects: list[DbtPlatformProject] = []
-    async with httpx.AsyncClient() as client:
+    async with httpx.AsyncClient(timeout=PLATFORM_API_TIMEOUT) as client:
         while True:
             response = await client.get(
                 f"{dbt_platform_url}/api/v3/accounts/{account.id}/projects/?state=1&offset={offset}&limit={page_size}",

src/dbt_mcp/semantic_layer/gql/gql_request.py

@@ -1,13 +1,14 @@
 import httpx
 
 from dbt_mcp.config.config_providers import SemanticLayerConfig
+from dbt_mcp.config.settings import SEMANTIC_LAYER_GQL_TIMEOUT
 from dbt_mcp.gql.errors import raise_gql_error
 
 
 async def submit_request(
     sl_config: SemanticLayerConfig,
     payload: dict,
-    timeout: float = 30.0,
+    timeout: float = SEMANTIC_LAYER_GQL_TIMEOUT,
 ) -> dict:
     if "variables" not in payload:
         payload["variables"] = {}