Error Handling Conventions

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• packages/core/src/check.test.ts
• packages/core/src/feed.test.ts
• apps/worker/src/webhook.handler.test.ts
• packages/core/src/statuspage-webhook.test.ts
• DEPLOYMENT.md

Error handling in StatusBeam is designed to prioritize system resilience, ensuring that the status page remains functional even when monitored services or internal components encounter failures. The architecture emphasizes graceful degradation over hard failures, particularly within the edge-native environment of Cloudflare Workers.

The core philosophy dictates that check functions never throw on the request path. Instead, network failures and validation errors are captured as specific state results (e.g., a "down" status) to ensure the cron execution completes and history is recorded. Non-critical failures in notifications or cache purging are logged rather than allowed to wedge the primary monitoring pipeline.

Sources: ARCHITECTURE.md:144-150, README.md:183-186

Failure Classification and Mapping

StatusBeam categorizes failures into distinct types, mapping them to standard system states. This ensures that transient network issues, configuration errors, and actual service outages are represented accurately in the D1 history.

Monitoring Check Failures

When a service check fails, the system avoids throwing exceptions to prevent crashing the check Worker. Instead, it generates a CheckResult with a specific status and error message.

Failure Scenario	Resulting Status	Mapped Error/Code
Network/Request Throw	down	code: 0, error: "network"
Unexpected HTTP Code	down	The actual HTTP status code (e.g., 500)
Response Time > Max	degraded	Preserves HTTP 200 code
Schema Validation Failure	down	"failed validation" message
Missing Component (Statuspage)	down	"component not found" message

Sources: ARCHITECTURE.md:144-147, packages/core/src/check.test.ts:39-44, packages/core/src/check.test.ts:205-212

Webhook Ingest Errors

The webhook handler (apps/worker/src/webhook.handler.ts) uses HTTP status codes to communicate ingest success or failure to upstream providers.

Resilient Data Processing

To maintain the "edge-first" promise, StatusBeam employs defensive programming patterns when reading from KV or D1 to ensure the UI can render even with malformed or missing data.

Graceful Degradation in Feeds and UI

The system uses fallbacks for missing or unparseable data points within incident feeds and badges. For example, if an incident has an unparseable timestamp, the feed generator defaults to the Unix epoch rather than throwing a RangeError.

• XML Escaping: All metadata (site names, incident titles) is escaped to prevent XML/HTML injection or breakage in Atom/RSS feeds.
• Timestamp Fallbacks: Unparseable dates default to 1970-01-01T00:00:00.000Z to maintain stable sorting and feed validity.
• Nullish Handling: Missing update bodies or titles are rendered as empty strings rather than "undefined" text.

Sources: packages/core/src/feed.test.ts:33-40, packages/core/src/feed.test.ts:109-115, packages/core/src/feed.test.ts:133-145

Schema Validation at Boundaries

StatusBeam uses zod to validate external data at the boundary. This includes:

1. Config Validation: status.config.yml is parsed via parseConfig to ensure slugs are safe for Cache-Tags.
2. Webhook Validation: Inbound payloads from Sentry or Statuspage are checked against zod.safeParse before processing.

Sources: ARCHITECTURE.md:147-148, packages/core/src/statuspage-webhook.test.ts:37-52

Error Logging and Diagnostics

StatusBeam follows a specific logging convention to aid debugging without leaking sensitive information.

• Redaction: URLs are redacted to their origin before being passed to notification logs to prevent leaking query parameters or tokens.
• Contextual Warnings: Logging (via console.warn / console.error) must always include context.
• Non-Fatal Failures: Failures in ctx.waitUntil tasks—such as dispatchNotifications or purgeStatusCache—are caught and logged. This prevents a single failing webhook or Cloudflare API error from blocking the completion of a check run.

Sources: ARCHITECTURE.md:131-133, ARCHITECTURE.md:152-154

Deployment and Infrastructure Errors

The statusbeam CLI and setup scripts handle environmental errors specifically related to Cloudflare's platform constraints.

Error Code/Message	Root Cause	Resolution
Authentication error [10000]	Account-owned token used for D1	Use a User API Token with Membership Read
d1 execute prompts	Interactive mode in CI	CLI passes --yes to auto-confirm
Cache Purge Failure	Missing CF_API_TOKEN or CF_ZONE_ID	Purge is skipped; fallback to 60s TTL
Missing KV summary	First cron has not executed	Trigger cron manually or wait for tick

Sources: DEPLOYMENT.md:52-58, DEPLOYMENT.md:142-152, scripts/setup.sh:220-225

---

Error handling in StatusBeam ensures that monitoring logic remains robust against external API volatility and that the public-facing status page prioritizes availability through safe data fallbacks and non-blocking background tasks.