Error Handling & Recovery
SECTION 28 — ERROR HANDLING & RECOVERY LADDERS
28.1 Image Upload Failure — Recovery Ladder
Scenario: An image upload to Cloudinary fails during Newsletter creation.| Attempt | Behavior |
|---|---|
| Attempt 1 | Backend silently retries the Cloudinary upload — no user interruption |
| Attempt 2 | Second silent auto-retry |
| Attempt 3 failure | Processing halts temporarily. Teacher receives in-app notification: “Image upload failed for [Headline]. Please re-upload or replace the image.” Teacher is given a re-upload option. |
| Re-upload Attempt 1 | Teacher re-uploads image. Backend attempts again. |
| Re-upload Attempt 2 | Another auto-retry. |
| Re-upload Attempt 3 failure | Error is silently logged. Document continues processing without the image. |
- A custom placeholder image is auto-generated from the news headline text for the affected section. This can be a server-side image with the headline text rendered on a neutral background.
- After PDF generation completes, the Teacher receives an in-app notification: “The following news items used auto-generated placeholder images due to upload failures: [list of headlines]. You can replace these images by editing the document.”
- All image failure events are logged in
metadata.image-failuresarray:\{ news-item-headline, failure-reason, placeholder-generated: true/false \}. - Editor sees the full failure log during their review queue processing.
- Editor has the ability to manually upload a replacement image for any placeholder-affected news section before triggering PDF generation.
28.2 Google Drive Sync Failure — Recovery
Scenario: A Google Drive sync operation fails (e.g. during finalisation or PDF delivery).| Attempt | Behavior |
|---|---|
| Attempt 1 | Backend silently retries the Drive API call |
| Attempt 2 | Second silent auto-retry |
| Both retries exhausted | Error is logged. Failure surfaces in Super Admin’s system dashboard AND Editor’s RBAC dashboard with full error response detail. Email notification sent to Super Admin and Editor with error response included. |
metadata.drive-sync-failures array: \{ attempted-at, error-code, error-message, path-attempted \}.
28.3 WeasyPrint PDF Generation Failure — Recovery
Scenario: WeasyPrint fails during PDF generation (either auto-triggered or manually triggered by Editor).| Attempt | Behavior |
|---|---|
| Attempts 1–N | Backend auto-retries WeasyPrint generation N times. N is configurable by the Super Admin in Super Admin System Settings → PDF Pipeline Configuration. Developer should implement a sensible default (recommended: 3 retries). |
| All N retries exhausted | Failure escalates to Super Admin and Editor. |
sla-paused = trueis set in the document metadata.- The SLA countdown clock pauses at its current value — it does not reset, and it does not continue counting while the failure is unresolved.
- Super Admin receives high-priority in-app notification AND email: “PDF generation failed for [Document Title] after [N] retries. Investigation required. Error: [error details].”
- Editor receives high-priority in-app notification AND email: “PDF generation failed for [Document Title]. The Super Admin has been notified and is investigating.”
- All organisation members receive a consolation in-app notification: “A processing issue was detected for [Document Title]. Our team is investigating.”
- The document is flagged in the Editor’s Kanban with an error indicator.
- Super Admin investigates the error from system-wide logs (template issue, malformed HTML, WeasyPrint config problem, etc.).
- Super Admin corrects the underlying issue or escalates to a software developer.
- Super Admin or Editor manually re-triggers PDF generation from the document detail view.
- On re-trigger:
sla-paused = false, SLA clock resumes from where it was frozen.
28.4 Storage Limit Failure — Drive & Neon DB
Scenario: A file upload to Google Drive or a data write to Neon DB fails due to storage limits.| System | Behavior on Storage Limit Hit |
|---|---|
| Google Drive | Immediate email + in-app notification to the affected user (Teacher or Editor) AND the Super Admin. Message includes: storage used, storage limit, recommended action. User must resolve (delete old files or upgrade storage) before further Drive syncs will succeed. Super Admin monitors storage alerts system-wide. |
| Neon DB | Same notification pattern. Backend suspends non-critical writes. Core document state writes are prioritised. Super Admin investigates and coordinates resolution. |
- These failures are non-silent — the user must take action.
- The system does not silently skip Drive uploads without notifying the user.
28.5 Real-Time Connection Loss (WebSocket / Realtime)
Scenario: The real-time connection between Teacher and Editor during active document review is lost.| Event | Behavior |
|---|---|
| Teacher connection drops | Teacher’s view shows: “Connection lost. Reconnecting…” loading state. |
| Reconnection success | Teacher’s view resyncs to the current document state automatically. Any changes made by the Editor during the disconnection are reflected immediately upon reconnect. |
| Reconnection failure after 3 attempts | Teacher sees: “Unable to reconnect to live collaboration. Please refresh the page.” |
28.6 General API Error Handling
- All FastAPI endpoints must return structured error responses:
\{ "error": true, "code": "ERROR_CODE", "message": "Human-readable message", "details": \{\} \}. - All frontend API calls must handle errors gracefully with user-facing messages. Silent failures are not acceptable for any user-triggered action.
- Rate limiting must be implemented on the FastAPI backend. On rate limit hit: return HTTP 429 with
Retry-Afterheader. Frontend shows: “Too many requests. Please wait a moment and try again.”