|
| 1 | +# Error Handling Guidelines |
| 2 | + |
| 3 | +When implementing or reviewing error handling in the codebase, follow these principles: |
| 4 | + |
| 5 | +## 1. Error Logging Requirements |
| 6 | + |
| 7 | +All `try-catch` blocks should log errors appropriately based on severity and context. |
| 8 | + |
| 9 | +## 2. Error Severity Levels |
| 10 | + |
| 11 | +Use appropriate logging levels based on the error type: |
| 12 | + |
| 13 | +- **ERROR level**: Use for unexpected errors, system failures, or critical issues that require immediate attention |
| 14 | +- **WARN level**: Use for user-related errors such as: |
| 15 | + - 401 Unauthorized (authentication issues) |
| 16 | + - 403 Forbidden (permission issues) |
| 17 | + - Other client errors (4xx status codes) caused by user actions |
| 18 | +- **DEBUG level**: Use for expected errors that don't require user intervention or are informational |
| 19 | + |
| 20 | +## 3. Retry Loop Handling |
| 21 | + |
| 22 | +When implementing retry logic: |
| 23 | + |
| 24 | +- **Do NOT log errors** on intermediate retry attempts |
| 25 | +- **Only log the error** if the final retry attempt fails |
| 26 | +- This prevents duplicate logging and log spam for transient issues |
| 27 | + |
| 28 | +Example pattern: |
| 29 | +```typescript |
| 30 | +let lastError; |
| 31 | +for (let attempt = 0; attempt < maxRetries; attempt++) { |
| 32 | + try { |
| 33 | + // operation |
| 34 | + return result; |
| 35 | + } catch (error) { |
| 36 | + lastError = error; |
| 37 | + if (attempt === maxRetries - 1) { |
| 38 | + // Log only on final failure |
| 39 | + logger.error('Operation failed after retries', error); |
| 40 | + } |
| 41 | + } |
| 42 | +} |
| 43 | +``` |
| 44 | + |
| 45 | +## 4. Dual Logging Requirement |
| 46 | + |
| 47 | +All error logging must be sent to **both**: |
| 48 | +- **Sentry**: For error tracking and monitoring |
| 49 | +- **Amplitude**: For analytics and user behavior tracking |
| 50 | + |
| 51 | +Ensure both logging calls are made for every logged error. |
| 52 | + |
| 53 | +## 5. No Duplicate Logging |
| 54 | + |
| 55 | +- Each error should only be logged **once** at the appropriate level |
| 56 | +- Avoid logging the same error at multiple levels (e.g., both ERROR and WARN) |
| 57 | +- If an error is caught and re-thrown, only log at the final catch location |
| 58 | +- Check if an error has already been logged before logging again |
| 59 | + |
| 60 | +## Implementation Checklist |
| 61 | + |
| 62 | +When adding error handling: |
| 63 | +- [ ] Choose appropriate severity level (ERROR/WARN/DEBUG) |
| 64 | +- [ ] If in retry loop, only log on final attempt |
| 65 | +- [ ] Send to both Sentry and Amplitude |
| 66 | +- [ ] Verify no duplicate logging in the call stack |
| 67 | +- [ ] Include relevant context (user action, request details, etc.) |
0 commit comments