Pattern: How to handle polling for APIs that may not be running witho...

Documentation for Sessions

🎨 Pattern: How to handle polling for APIs that may not be running witho...

Date: 2026-03-17
Time: 17:17:11 UTC
Session: gspace1-229.6
Agent: storage
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

How to handle polling for APIs that may not be running without flooding the browser console with 500 errors?

Task: Not specified

🎯 Decision Made

Chosen:

Three-tier smart polling strategy: (1) Track reachable vs unreachable APIs from health check results. (2) For unreachable APIs, cache the 'Unreachable' result and return it from memory — zero network requests. Re-probe unreachable APIs only every 60s (6 cycles × 10s). (3) Per-API tracking toggle persisted to localStorage — users can fully disable APIs they know aren't running (like docs-api). Disabled APIs produce zero network traffic.

Options Considered:

  1. Poll everything and accept console noise (bad DX)
  2. Only poll on manual refresh (loses real-time value)
  3. Exponential backoff per API (complex, still makes requests)
  4. User toggle + cached unreachable + slow re-probe (chosen — eliminates noise completely)

💭 Reasoning

Browser console always logs failed XHR requests as red errors — this cannot be suppressed by catchError. The only way to eliminate console noise is to not make the request at all. The health check runs first and determines reachability, then activity polling only hits reachable APIs. The 60s re-probe interval balances between detecting recovery and minimizing noise. The user toggle (persisted to localStorage) handles the common case where docs-api is intentionally not running — this is a dev workflow reality, not an error. The proxy returns 500 (not 502) when the backend is unreachable, so we treat status 0 and 500 the same as 'Unreachable'.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation