Fix #772: Improve OpenAI error messages with user-friendly parsing and hints

[snowykte0426]

Summary

This PR improves OpenAI API error messages by implementing structured JSON parsing and providing user-friendly error messages with contextual hints, addressing issue #772.

Problem

Previously, OpenAI API errors were displayed in raw JSON format, making them difficult for users to understand:

Before:

401 - {"error":{"message":"Incorrect API key provided: sk-proj-*********************************************F2yw. You can find your API key at https://platform.openai.com/account/api-keys.","type":"invalid_request_error","param":null,"code":"invalid_api_key"}}

Solution

The error messages are now parsed and displayed in a user-friendly format with helpful hints:

After:

OpenAI Authentication Error: Incorrect API key provided: sk-proj-*********************************************F2yw. You can find your API key at https://platform.openai.com/account/api-keys. (Please check your API key at https://platform.openai.com/account/api-keys)

Changes Made

New Classes

• OpenAiErrorResponse: POJO for parsing OpenAI JSON error response structure
• OpenAiErrorMessageImprover: Utility class for improving error messages with:
  • JSON parsing of OpenAI error responses
  • Status-based error prefixes (401 → "Authentication Error", 429 → "Rate Limit Error", etc.)
  • Contextual hints based on error codes
  • Graceful fallback to original format when parsing fails

Dependencies

• Added spring-boot-starter-json dependency to spring-ai-retry module for Jackson JSON processing

Error Message Improvements

• Authentication errors (401): Direct users to API key management
• Rate limit errors (429): Provide guidance on quota and timing
• Model errors: Help with model name verification
• Context length errors: Suggest input reduction

Testing

• Unit tests: Comprehensive test coverage for all error scenarios
• Integration tests: Verified with actual OpenAI API error responses
• Backward compatibility: Maintains original behavior for non-JSON responses
• Format validation: All code passes Spring Java Format validation

Related Issues

Resolves #772: OpenAI - improve error messages when there is a connection error