feature #543 [Platform][OpenAI] Add AuthenticationException for better error handling (vitalii-kyktov, vitality)

This PR was merged into the main branch.

Discussion
----------

[Platform][OpenAI] Add AuthenticationException for better error handling

| Q             | A
| ------------- | ---
| Branch?       | main
| Bug fix?      | yes
| New feature?  | no
| Deprecations? | no
| Tickets       | Fix #528
| License       | MIT

When OpenAI API returns 401 (authentication error), users now get a clear AuthenticationException with the actual API error message instead of the confusing "Response does not contain choices" error.

Changes:
- Add AuthenticationException class for API authentication failures
- Update OpenAI ResultConverter to check HTTP 401 status before processing
- Add test coverage for authentication error scenarios

Commits
-------

193b56a [Platform][OpenAI] remove incomplete `@author` tags from AuthenticationException
7da46cb [Platform][OpenAI] simplify authentication error test structure
56881ba [Platform][OpenAI] Add AuthenticationException for better error handling

Author: chr-hertel

src/platform/src/Bridge/OpenAi/Gpt/ResultConverter.php

@@ -12,6 +12,7 @@
 namespace Symfony\AI\Platform\Bridge\OpenAi\Gpt;
 
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt;
+use Symfony\AI\Platform\Exception\AuthenticationException;
 use Symfony\AI\Platform\Exception\ContentFilterException;
 use Symfony\AI\Platform\Exception\RuntimeException;
 use Symfony\AI\Platform\Model;
@@ -42,6 +43,13 @@ public function supports(Model $model): bool
 
     public function convert(RawResultInterface|RawHttpResult $result, array $options = []): ResultInterface
     {
+        $response = $result->getObject();
+
+        if (401 === $response->getStatusCode()) {
+            $errorMessage = json_decode($response->getContent(false), true)['error']['message'];
+            throw new AuthenticationException($errorMessage);
+        }
+
         if ($options['stream'] ?? false) {
             return new StreamResult($this->convertStream($result->getObject()));
         }

src/platform/src/Exception/AuthenticationException.php

@@ -0,0 +1,22 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Platform\Exception;
+
+/**
+ * Exception thrown when API authentication fails.
+ *
+ * @author Vitalii Kyktov <vitalii.kyktov@gmail.com>
+ * @author Dmytro Liashko <dmlyashko@gmail.com>
+ */
+class AuthenticationException extends RuntimeException
+{
+}

src/platform/tests/Bridge/OpenAi/Gpt/ResultConverterTest.php

@@ -16,6 +16,7 @@
 use PHPUnit\Framework\Attributes\UsesClass;
 use PHPUnit\Framework\TestCase;
 use Symfony\AI\Platform\Bridge\OpenAi\Gpt\ResultConverter;
+use Symfony\AI\Platform\Exception\AuthenticationException;
 use Symfony\AI\Platform\Exception\ContentFilterException;
 use Symfony\AI\Platform\Exception\RuntimeException;
 use Symfony\AI\Platform\Result\ChoiceResult;
@@ -155,6 +156,23 @@ public function getResponse(): ResponseInterface
         $converter->convert(new RawHttpResult($httpResponse));
     }
 
+    public function testThrowsAuthenticationExceptionOnInvalidApiKey()
+    {
+        $converter = new ResultConverter();
+        $httpResponse = self::createMock(ResponseInterface::class);
+        $httpResponse->method('getStatusCode')->willReturn(401);
+        $httpResponse->method('getContent')->willReturn(json_encode([
+            'error' => [
+                'message' => 'Invalid API key provided: sk-invalid',
+            ],
+        ]));
+
+        $this->expectException(AuthenticationException::class);
+        $this->expectExceptionMessage('Invalid API key provided: sk-invalid');
+
+        $converter->convert(new RawHttpResult($httpResponse));
+    }
+
     public function testThrowsExceptionWhenNoChoices()
     {
         $converter = new ResultConverter();