Back to Dashboard
Failure & Recovery Paths src/api/events.py
What AGS should do when the normal path breaks. Most failures degrade capture quality or delay support; they should not silently corrupt research data.
| Failure | System response | Researcher check |
|---|---|---|
| Consent missing | Reject telemetry with 403; do not write event rows. | Alerts and participant onboarding state. |
| Proxy upstream timeout/error | Show plain recovery page or fallback notice; log technical error. | Alerts, proxy logs, affected template/site. |
| CAPTCHA or anti-frame page | Attempt extension handoff if installed; otherwise show fallback guidance. | Capture channel, extension install status, step outcomes. |
| Extension missing | Continue proxy/limited mode where possible; avoid pretending full capture exists. | Sessions capture metadata and signal completeness. |
| Offline | Queue events/help/session end/survey locally and replay idempotently. | Replay gaps, duplicate client_event_id rejection, session timeline. |
| Redis cache miss | Rebuild deterministic session context from PostgreSQL; never invalidate session just for cache miss. | Redis memory/eviction and cache miss alerts. |
| Low signal confidence | Withhold via confidence gate instead of firing a weak intervention. | Signal detail, sparse events, baseline quality. |
| LLM timeout/slow network | Use scripted fallback help and log routing decision. | LLM timeout alerts and content coverage gaps. |
| Template schema mismatch | Reject incompatible session/template flow with conflict response. | Template version and deployment mismatch. |
| Intervention worsens outcome | Write adaptation failure, back off with cooldown, factor into later decisions. | Adaptation failures by content, step, language, condition. |
Recovery principle. Prefer explicit degraded state over fake completeness. If AGS only has limited capture, downstream analysis should be able to see that.