Improve API error message formatting

[benodiwal]

Description

The formatAPIError() function in src/utils.cpp currently provides basic error formatting. It should be enhanced to handle common API error scenarios with user-friendly messages.

Note: This improvement was marked with CR-someday in the codebase, indicating it was planned for future enhancement.

File to Update

src/utils.cpp - formatAPIError() function

Task

Enhance the error formatting to handle these common scenarios:

1. Rate limits: "You've exceeded the API rate limit. Please wait and try again."
2. Authentication errors: "Invalid API key. Please check your configuration."
3. Quota exceeded: "Your API quota has been exceeded. Check your usage limits."
4. Timeout errors: "Request timed out. The AI service may be slow or unavailable."
5. Invalid request: "The request was invalid. This may be a bug in pg_ai_query."
6. Service unavailable: "The AI service is temporarily unavailable. Please try again later."

Example Implementation

std::string formatAPIError(const std::string& provider, 
                           int status_code, 
                           const std::string& error_body) {
    std::string user_message;
    
    // Parse error body for specific error types
    if (status_code == 429 || error_body.find("rate_limit") != std::string::npos) {
        user_message = "Rate limit exceeded. Please wait before making more requests.";
    } 
    else if (status_code == 401 || error_body.find("invalid_api_key") != std::string::npos) {
        user_message = "Invalid API key for " + provider + ". "
                       "Please check your ~/.pg_ai.config file.";
    }
    else if (status_code == 402 || error_body.find("quota") != std::string::npos) {
        user_message = "API quota exceeded. Check your " + provider + " account usage.";
    }
    else if (status_code == 408 || error_body.find("timeout") != std::string::npos) {
        user_message = "Request timed out. Try increasing request_timeout_ms in config.";
    }
    else if (status_code == 503 || status_code == 502) {
        user_message = provider + " service is temporarily unavailable. Try again later.";
    }
    else if (status_code >= 400 && status_code < 500) {
        user_message = "Request error (" + std::to_string(status_code) + "): " + error_body;
    }
    else {
        user_message = provider + " API error: " + error_body;
    }
    
    return user_message;
}

Acceptance Criteria

• Rate limit errors have clear, actionable messages
• Auth errors point users to config file
• Timeout errors suggest config changes
• Generic errors still show useful information
• Messages are consistent across providers

Skills Required

• C++
• HTTP status codes understanding
• API error handling patterns

Difficulty

🟡 Medium - Improves user experience significantly

[UltraInstinct21]

Hi!
I have opened a PR to improve the API error message formats, initially some CI checks were failing. I have fixed them by restoring the legacy formatAPIError(const std::string&) overload for backward compatibility.

[AlinawazHusain]

Hi ,
I completed the function with appropriate error messages handling all cases