mirror of https://github.com/AutoMaker-Org/automaker.git synced 2026-01-30 06:12:03 +00:00

Files

shevanio 76ad6667f1 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.

2025-12-29 13:50:08 +01:00

4.3 KiB

Raw Blame History

Improved Error Handling for Rate Limiting

Problem

When running multiple features concurrently in auto-mode, the Claude API rate limits were being exceeded, resulting in cryptic error messages:

Error: Claude Code process exited with code 1

This error provided no actionable information to users about:

What went wrong (rate limit exceeded)
How long to wait before retrying
How to prevent it in the future

Root Cause

The Claude Agent SDK was terminating with exit code 1 when hitting rate limits (HTTP 429), but the error details were not being properly surfaced to the user. The error handling code only showed the generic exit code message instead of the actual API error.

Solution

Implemented comprehensive rate limit error handling across the stack:

1. Enhanced Error Classification (libs/utils)

Added new error type and detection functions:

New error type: 'rate_limit' added to ErrorType union
isRateLimitError(): Detects 429 and rate_limit errors
extractRetryAfter(): Extracts retry duration from error messages
Updated classifyError(): Includes rate limit classification with retry-after metadata
Updated getUserFriendlyErrorMessage(): Provides clear, actionable messages for rate limit errors

2. Improved Claude Provider Error Handling (apps/server)

Enhanced ClaudeProvider.executeQuery() to:

Classify all errors using the enhanced error utilities
Detect rate limit errors specifically
Provide user-friendly error messages with:
- Clear explanation of the problem (rate limit exceeded)
- Retry-after duration when available
- Actionable tip: reduce maxConcurrency in auto-mode
Preserve original error details for debugging

3. Comprehensive Test Coverage

Added 8 new tests covering:

Rate limit error detection (429, rate_limit keywords)
Retry-after extraction from various message formats
Error classification with retry metadata
User-friendly message generation
Edge cases (null/undefined, non-rate-limit errors)

Total test suite: 162 tests passing ✅

User-Facing Changes

Before

[AutoMode] Feature touch-gesture-support failed: Error: Claude Code process exited with code 1

After

[AutoMode] Feature touch-gesture-support failed: Rate limit exceeded (429). Please wait 60 seconds before retrying.

Tip: If you're running multiple features in auto-mode, consider reducing concurrency (maxConcurrency setting) to avoid hitting rate limits.

Benefits

Clear communication: Users understand exactly what went wrong
Actionable guidance: Users know how long to wait and how to prevent future errors
Better debugging: Original error details preserved for technical investigation
Type safety: New isRateLimit and retryAfter fields properly typed in ErrorInfo
Comprehensive testing: All edge cases covered with automated tests

Technical Details

Files Modified

libs/types/src/error.ts - Added 'rate_limit' type and retryAfter field
libs/utils/src/error-handler.ts - Added rate limit detection and extraction logic
libs/utils/src/index.ts - Exported new utility functions
libs/utils/tests/error-handler.test.ts - Added 8 new test cases
apps/server/src/providers/claude-provider.ts - Enhanced error handling with user-friendly messages

API Changes

ErrorInfo interface (backwards compatible):

interface ErrorInfo {
  type: ErrorType; // Now includes 'rate_limit'
  message: string;
  isAbort: boolean;
  isAuth: boolean;
  isCancellation: boolean;
  isRateLimit: boolean; // NEW
  retryAfter?: number; // NEW (seconds to wait)
  originalError: unknown;
}

New utility functions:

isRateLimitError(error: unknown): boolean
extractRetryAfter(error: unknown): number | undefined

Future Improvements

This PR lays the groundwork for future enhancements:

Automatic retry with exponential backoff: Use retryAfter to implement smart retry logic
Global rate limiter: Track requests to prevent hitting limits proactively
Concurrency auto-adjustment: Dynamically reduce concurrency when rate limits are detected
User notifications: Show toast/banner when rate limits are approaching

Testing

Run tests with:

npm run test -w @automaker/utils

All 162 tests pass, including 8 new rate limit tests.

4.3 KiB Raw Blame History