Skip to main content

Developer Portal Service — Failure Modes

Version: 1.0 Status: Draft Owner: Product + Developer Relations (DevRel) Last Updated: 2026-04-20

1. Intent​

Catalogue what can break in the Developer Portal, the user impact, the detection signal, and the mitigation. Portal failure must never affect production data plane (SMS dispatch, MNO interconnect).

2. Failure Catalog​

F1 — Docs CDN cache stale on new release​

  • Impact: Developers see old API reference. TBD
  • Detection: Release manifest hash mismatch. TBD
  • Mitigation: Automated cache purge on publish; manual purge runbook. TBD

F2 — auth-service gRPC unavailable​

  • Impact: Key creation / revocation / Verify calls fail. TBD
  • Detection: circuit breaker open metric. TBD
  • Mitigation: Surface 503 to portal UI; queue key-revocation events for retry; fail Verify start with 503. TBD

F3 — Verify code compromise (Redis breach)​

  • Impact: OTPs leaked. TBD
  • Detection: Anomalous Redis access pattern; KMS pepper rotation alarm. TBD
  • Mitigation: Pepper is in-memory + KMS-rotated; codes are HMAC, not plaintext, so leak does not yield codes. TBD

F4 — Verify channel fallback storm​

  • Impact: WhatsApp fail → SMS retry → Voice retry per session amplifies to 3x dispatch. TBD
  • Detection: Verify dispatch ratio > 1.8x sessions in 5m. TBD
  • Mitigation: Per-tenant cap, per-recipient cap, circuit breaker per channel. TBD

F5 — SDK release publishes only some languages​

  • Impact: Version skew across SDKs. TBD
  • Detection: Pipeline alert on partial publish. TBD
  • Mitigation: DevRel-driven manual completion runbook; auto-issue created. TBD

F6 — Snippet generator returns insecure code​

  • Impact: Developers copy-paste broken or insecure samples. TBD
  • Detection: snippet-validation CI; user reports. TBD
  • Mitigation: Snippet templates are reviewed; AI-only-for-prose policy; per-snippet test suite in CI. TBD

F7 — Production key shown in shared session screenshot​

  • Impact: Customer leaks own credential. TBD
  • Mitigation: "Show secret" requires re-MFA; secret-render screen warns about screenshots; one-time view. TBD

3. DR Posture​

  • TBD