Broker Status Page Monitoring Integration

When to Use

Invoke this skill when an order submission fails, a WebSocket drops, or a REST call times out, and the on-call question is is this the broker or is it us? Answering it by hand costs minutes at exactly the wrong moment. This skill polls the broker's public Statuspage v2 feed, scopes the reading to the components your order flow actually uses, and returns a classification an incident pipeline can route on.

The two wrong answers are expensive in opposite directions, and the whole design follows from that asymmetry:

• Wrongly answering "broker" suppresses the ticket for a live bug in your own code and, in most deployments, trips a circuit breaker. The bug stays in production because the pager never fired.
• Wrongly answering "us" sends an engineer to debug working code during a broker incident, when their attention is worth the most.

So each confident verdict requires positive evidence. EXTERNAL_BROKER_OUTAGE requires fresh evidence of impairment; INTERNAL_APPLICATION_BUG requires fresh evidence of health. Everything else — no reading, a stale reading, an unreachable feed, an unrecognised value, or a merely degraded page — returns UNKNOWN_FAILURE, which routes a human to the incident instead of resolving it automatically in either direction.

When NOT to Use

• As an outage detector. A status page is a human-published artifact, updated after the broker's ops team notices, triages and decides to disclose. OPERATIONAL means "nothing has been published", never "nothing is wrong". Pair it with a first-party signal — reject rates, heartbeat latency, disconnect counts — and treat this as the corroborating input, not the trigger.
• As the circuit breaker. This classifies; it does not halt trading, cancel orders or flatten positions. Wire the verdict into kill-switch-and-drawdown-circuit-breakers, and route around the broker with broker-failover-secondary-account-routing.
• For scheduled API retirements. A sunset date is a planned deprecation, not an unplanned outage — see broker-api-deprecation-notice-monitoring.
• For brokers without a Statuspage feed. The parser is specific to the Atlassian Statuspage v2 schema. A broker publishing status as an HTML page, an RSS feed or a Twitter account needs a different ingestion path; do not point this at an arbitrary URL and assume the absence of a status object means healthy.
• As a retry gate on an ambiguous order state. "The broker is up" is not evidence that your timed-out order was not accepted. That is order-placement-idempotency, and this skill's verdict must never be used to justify a blind resubmission.

Prerequisites

• Each broker's Statuspage v2 summary URL — the full URL including /api/v2/summary.json, e.g. https://status.alpaca.markets/api/v2/summary.json. These are public and unauthenticated; private and trial pages require an API key in an Authorization header.
• The exact component names your order flow depends on, copied from the feed's components[].name. Without these the monitor can only reason over the blended page-wide indicator, which is both too noisy (an unrelated minor incident) and too quiet (a dead trading component under a green page).
• An HTTP transport that enforces a connect and read timeout. The diagnosis path runs inside an order-failure handler; an untimed socket there converts a failed order into a hung strategy.
• A poll interval. 60s is a reasonable default; polling faster than ~10s is wasted work — see Common Pitfalls.

Workflow

1. Ingest summary.json. GET the full summary URL. The response carries page, status, components, incidents and scheduled_maintenances. Treat a non-200, a transport exception, or a payload without a status object as no evidence — never as an all-clear.

2. Map status.indicator, and refuse to guess. none → OPERATIONAL, minor → DEGRADED, major/critical → MAJOR_OUTAGE, maintenance → MAINTENANCE. Anything else maps to UNKNOWN. Do not default unrecognised strings to the worst case: a typo or a future enum value would then trigger an automatic trading halt and an automatic ticket suppression off a string nobody validated.

3. Scope to the components you depend on. Match your declared component names against components[].name and reduce their statuses to the worst one (partial_outage counts as an outage; a missing or unrecognised status counts as UNKNOWN, never as operational). This component-scoped state overrides the page indicator when it is known — it is what catches a dead order-routing component under a green page, and what stops an incident on a component you never call from silencing your bug tickets. If a declared name matches nothing, alert on it: the broker renamed a component and your scoping is now silently off.

4. Check freshness before classifying. A reading older than the configured bound (default 300s) is not evidence. Measure age from your own fetch clock — not from page.updated_at, which is a last-changed timestamp: both feeds verified for this skill carried a healthy page.updated_at several hours old.

5. Classify, in this order.

   Evidence	Verdict
   No reading, or older than the freshness bound	UNKNOWN_FAILURE
   A declared dependency component is impaired	EXTERNAL_BROKER_OUTAGE
   Page impaired, but every dependency reads operational	UNKNOWN_FAILURE
   Page impaired, no dependency evidence	EXTERNAL_BROKER_OUTAGE
   Anything merely degraded, or unrecognised	UNKNOWN_FAILURE
   Page operational	INTERNAL_APPLICATION_BUG

6. Route the verdict. EXTERNAL_BROKER_OUTAGE suppresses the code-bug escalation and trips the circuit breaker. INTERNAL_APPLICATION_BUG pages the owning engineer. UNKNOWN_FAILURE pages a human and suppresses nothing — it is the correct answer far more often than a two-way classifier admits.

Full procedure, decision-table rationale and the EMS/alerting contract: see references/workflows.md. Endpoint evidence, schema and verified vendor claims: see references/standards.md. Printable pre-flight checklist: see assets/checklist.md.

Common Pitfalls

• Treating "I could not reach the status page" as "the broker is fine". This is the single worst failure mode here, because it fires exactly when the broker is in trouble. An unreachable feed, an HTTP 500, a missing transport or an unconfigured broker key are all absence of evidence, and must classify as undetermined — never as an operational platform.
• Suppressing a bug ticket on a minor indicator. minor is the page-wide roll-up of any small published incident — a degraded docs site, a slow web dashboard. It is consistent with both a broker fault and your own bug, so it justifies neither verdict. Suppressing on minor means a real bug in your order construction goes unexamined for as long as an unrelated incident stays open.
• Trusting a green page you fetched from a CDN. Both verified endpoints serve Cache-Control: max-age=10, public, s-maxage=10, stale-while-revalidate=20, stale-if-error=3600. That stale-if-error=3600 means that when Statuspage's own origin fails, the edge may keep serving the last good body — a green "All Systems Operational" — for up to an hour.
• Using page.updated_at as a freshness check. It records when the page last changed, not when it was last confirmed. A healthy page that has not changed in days carries a days-old timestamp; treating that as staleness turns every quiet period into an alert. Measure age from your own fetch instead.
• Reading the page indicator and stopping there. status.indicator is a blend across every component on the page. Alpaca publishes 112 components in 11 groups, Coinbase 172 in 7 — an outage confined to "Broker API (Sandbox)" while you trade live is invisible in your decision if you only scope to the components you use, and an outage confined to your component can sit under a page-wide none.
• Double-counting component groups. Group entries ("group": true) appear in the same components array as their children and carry a rolled-up status, so a single failing child reports as two impaired components unless groups are separated out.
• Reading a missing component status as operational. A status field that is absent, null or an unrecognised string is unreadable, not healthy. Folding it into an all-clear is how a schema change becomes a silent mis-diagnosis.
• Polling faster to detect outages sooner. The public Status API is documented as not rate limited, so the risk is not an IP block — it is that max-age=10 means a refetch inside 10 seconds returns the identical cached body. Sub-cache polling buys no freshness. (The separate, token-authenticated Manage API is limited — 60 req/min per page, 1 req/s per token, 429 plus Retry-After — but that is not the API you poll here.)
• Fetching the status page once per failed order. A broker incident produces a burst of failures, and a diagnoser that refreshes on each one issues a fetch storm and adds network latency to every failure handler. Bound the implicit refresh to the cache TTL.
• Blocking the order path on an untimed HTTP call. The diagnosis runs inside an exception handler on the trading thread. Without a transport timeout, one hung status fetch stalls the strategy that was already failing.
• Letting the diagnoser raise. An exception thrown while classifying an execution failure displaces the original trading exception and destroys the forensic trail.

Verification

• Run the unit suite and confirm every test passes: python -m unittest discover -s skills/broker-status-page-monitoring-integration/scripts
• Assert an unreachable feed (HTTP 500, transport exception, missing transport, unknown broker key) yields UNKNOWN_FAILURE with platform_state UNKNOWN — never INTERNAL_APPLICATION_BUG and never OPERATIONAL. This is the highest-value single assertion in the suite.
• Assert a minor indicator yields UNKNOWN_FAILURE, not EXTERNAL_BROKER_OUTAGE.
• Assert an unrecognised status.indicator yields UNKNOWN, not MAJOR_OUTAGE.
• Assert a dependency component in major_outage under a page indicator of none still yields EXTERNAL_BROKER_OUTAGE.
• Assert a critical page with all declared dependencies operational yields UNKNOWN_FAILURE rather than suppressing the ticket.
• Assert a reading older than the freshness bound is refetched, and yields UNKNOWN_FAILURE when the refetch also fails.
• Assert a component whose status key is absent does not count toward an all-clear.
• Assert a group and its failing child are not both listed as affected components.
• Assert a burst of 50 diagnoses issues one status fetch, not 50.
• Smoke-test against the live feeds with a timeout-enforcing transport and confirm your declared component names appear in unmatched_dependencies as an empty list.

Related Skills

• broker-failover-secondary-account-routing
• kill-switch-and-drawdown-circuit-breakers
• broker-api-deprecation-notice-monitoring
• circuit-breaker-for-downstream-service-calls
• structured-logging-for-post-incident-forensics
• order-placement-idempotency
• vendor-outage-fallback-data-source-hierarchy