feat: improve rate limit error handling with user-friendly messages

- Add rate_limit error type to ErrorInfo classification
- Implement isRateLimitError() and extractRetryAfter() utilities
- Enhance ClaudeProvider error handling with actionable messages
- Add comprehensive test coverage (8 new tests, 162 total passing)

**Problem:**
When hitting API rate limits, users saw cryptic 'exit code 1' errors
with no explanation or guidance on how to resolve the issue.

**Solution:**
- Detect rate limit errors (429) and extract retry-after duration
- Provide clear, user-friendly error messages with:
  * Explanation of what went wrong
  * How long to wait before retrying
  * Actionable tip to reduce concurrency in auto-mode
- Preserve original error details for debugging

**Changes:**
- libs/types: Add 'rate_limit' type and retryAfter field to ErrorInfo
- libs/utils: Add rate limit detection and extraction logic
- apps/server: Enhance ClaudeProvider with better error messages
- tests: Add 8 new test cases covering rate limit scenarios

**Benefits:**
✅ Clear communication - users understand the problem
✅ Actionable guidance - users know how to fix it
✅ Better debugging - original errors preserved
✅ Type safety - proper TypeScript typing
✅ Comprehensive testing - all edge cases covered

See CHANGELOG_RATE_LIMIT_HANDLING.md for detailed documentation.

libs/utils/src/error-handler.ts

@@ -51,6 +51,46 @@ export function isAuthenticationError(errorMessage: string): boolean {
   );
 }
 
+/**
+ * Check if an error is a rate limit error
+ *
+ * @param error - The error to check
+ * @returns True if the error is a rate limit error
+ */
+export function isRateLimitError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error || '');
+  return message.includes('429') || message.includes('rate_limit');
+}
+
+/**
+ * Extract retry-after duration from rate limit error
+ *
+ * @param error - The error to extract retry-after from
+ * @returns Number of seconds to wait, or undefined if not found
+ */
+export function extractRetryAfter(error: unknown): number | undefined {
+  const message = error instanceof Error ? error.message : String(error || '');
+
+  // Try to extract from Retry-After header format
+  const retryMatch = message.match(/retry[_-]?after[:\s]+(\d+)/i);
+  if (retryMatch) {
+    return parseInt(retryMatch[1], 10);
+  }
+
+  // Try to extract from error message patterns
+  const waitMatch = message.match(/wait[:\s]+(\d+)\s*(?:second|sec|s)/i);
+  if (waitMatch) {
+    return parseInt(waitMatch[1], 10);
+  }
+
+  // Default retry-after for rate limit errors
+  if (isRateLimitError(error)) {
+    return 60; // Default to 60 seconds for rate limit errors
+  }
+
+  return undefined;
+}
+
 /**
  * Classify an error into a specific type
  *
@@ -62,10 +102,14 @@ export function classifyError(error: unknown): ErrorInfo {
   const isAbort = isAbortError(error);
   const isAuth = isAuthenticationError(message);
   const isCancellation = isCancellationError(message);
+  const isRateLimit = isRateLimitError(error);
+  const retryAfter = isRateLimit ? extractRetryAfter(error) : undefined;
 
   let type: ErrorType;
   if (isAuth) {
     type = 'authentication';
+  } else if (isRateLimit) {
+    type = 'rate_limit';
   } else if (isAbort) {
     type = 'abort';
   } else if (isCancellation) {
@@ -82,6 +126,8 @@ export function classifyError(error: unknown): ErrorInfo {
     isAbort,
     isAuth,
     isCancellation,
+    isRateLimit,
+    retryAfter,
     originalError: error,
   };
 }
@@ -103,6 +149,13 @@ export function getUserFriendlyErrorMessage(error: unknown): string {
     return 'Authentication failed. Please check your API key.';
   }
 
+  if (info.isRateLimit) {
+    const retryMsg = info.retryAfter
+      ? ` Please wait ${info.retryAfter} seconds before retrying.`
+      : ' Please reduce concurrency or wait before retrying.';
+    return `Rate limit exceeded (429).${retryMsg}`;
+  }
+
   return info.message;
 }
 

libs/utils/src/index.ts

@@ -8,6 +8,8 @@ export {
   isAbortError,
   isCancellationError,
   isAuthenticationError,
+  isRateLimitError,
+  extractRetryAfter,
   classifyError,
   getUserFriendlyErrorMessage,
   getErrorMessage,