Report 4.1.3 — Error Handling Detailed Guide
This document elaborates on how the system reacts when transcripts are incomplete or when upstream APIs fail.
Transcript Analysis Failures
OpenAIService and ActionItemExtractorService follow a layered defense:
- If OpenAI returns an empty completion,
OpenAIService.getCompletion() retries with a stricter prompt.
- If OpenAI returns invalid JSON, the extractor strips fences and attempts to parse again.
- When parsing still fails, the raw response is stored as
raw_output under a single action-item entry so downstream handlers do not crash.
- Any exception while contacting OpenAI bubble up to the controller so the API consumer is informed, while the server logs the stack trace.
HubSpot API Failures
For deal creation and deletion:
- Each POST/DELETE call is wrapped in a try/catch; exceptions increment
failedCount and append a HubSpotDealDeletionStatus or error string.
- Deletion loops log failures but continue processing remaining IDs to maximize cleanup coverage.
- The resulting report (creation or deletion) summarizes successes and failures clearly so callers can alert QA or operators.
Operator Guidance
- Inspect
HubSpotDealDeletionReport.statuses for per-deal outcomes.
- Retry failed batches manually using the IDs logged in the report.
System-Level Resilience
Additional safeguards:
- Controller endpoints catch exceptions and respond with HTTP error codes plus messages describing the cause.
- Logs capture precise timestamps, enabling tracing when transcripts arrive incomplete or APIs time out.
- Behavioral diagrams highlight the fallback paths (see
plantuml/behavior/uml_behavioral_state_diagram.html and uml_activity_diagram.html).