Changeset 62037 for trunk/src/wp-includes/ai-client/class-wp-ai-client-prompt-builder.php

Timestamp:

03/17/2026 02:28:40 PM (7 months ago)

Author:

flixos90

Message:

AI: Improve AI Client error handling.

Prior to this changeset, the WordPress AI Client would handle every exception thrown in the PHP AI Client in the same way, losing meaningful nuance about different kinds of errors along the way.

Now, the WP_Error objects returned by the WordPress AI Client come with more helpful error codes, and they include semantic HTTP status codes as well so that they can be used in relevant contexts out of the box, like e.g. the REST API.

Props flixos90, gziolo.
Fixes #64867.
See #64591.

File:

• trunk/src/wp-includes/ai-client/class-wp-ai-client-prompt-builder.php (modified) (6 diffs)

trunk/src/wp-includes/ai-client/class-wp-ai-client-prompt-builder.php

@@ -9 +9 @@
 
 use WordPress\AiClient\Builders\PromptBuilder;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\TokenLimitReachedException;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
@@ -16 +18 @@
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
 use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
+use WordPress\AiClient\Providers\Http\Exception\ClientException;
+use WordPress\AiClient\Providers\Http\Exception\NetworkException;
+use WordPress\AiClient\Providers\Http\Exception\ServerException;
 use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
@@ -180 +185 @@
                 } catch ( Exception $e ) {
                         $this->builder = new PromptBuilder( $registry );
-                        $this->error   = new WP_Error(
-                                'prompt_builder_error',
-                                $e->getMessage(),
-                                array(
-                                        'exception_class' => get_class( $e ),
-                                )
-                        );
+                        $this->error   = $this->exception_to_wp_error( $e );
                 }
 
@@ -312 +311 @@
                                         __( 'Prompt execution was prevented by a filter.' ),
                                         array(
-                                                'exception_class' => 'WP_AI_Client_Prompt_Prevented',
+                                                'status' => 503,
                                         )
                                 );
@@ -334 +333 @@
                         return $result;
                 } catch ( Exception $e ) {
-                        $this->error = new WP_Error(
-                                'prompt_builder_error',
-                                $e->getMessage(),
-                                array(
-                                        'exception_class' => get_class( $e ),
-                                )
-                        );
+                        $this->error = $this->exception_to_wp_error( $e );
 
                         if ( self::is_generating_method( $name ) ) {
@@ -347 +340 @@
                         return $this;
                 }
+        }
+
+        /**
+         * Converts an exception into a WP_Error with a structured error code and message.
+         *
+         * This method maps different exception types to specific WP_Error codes and HTTP status codes.
+         * The presence of the status codes means these WP_Error objects can be easily used in REST API responses
+         * or other contexts where HTTP semantics are relevant.
+         *
+         * @since 7.0.0
+         *
+         * @param Exception $e The exception to convert.
+         * @return WP_Error The resulting WP_Error object.
+         */
+        private function exception_to_wp_error( Exception $e ): WP_Error {
+                if ( $e instanceof NetworkException ) {
+                        $error_code  = 'prompt_network_error';
+                        $status_code = 503;
+                } elseif ( $e instanceof ClientException ) {
+                        // `ClientException` uses HTTP status codes as exception codes, so we can rely on them.
+                        $error_code  = 'prompt_client_error';
+                        $status_code = $e->getCode() ? $e->getCode() : 400;
+                } elseif ( $e instanceof ServerException ) {
+                        // `ServerException` uses HTTP status codes as exception codes, so we can rely on them.
+                        $error_code  = 'prompt_upstream_server_error';
+                        $status_code = $e->getCode() ? $e->getCode() : 500;
+                } elseif ( $e instanceof TokenLimitReachedException ) {
+                        $error_code  = 'prompt_token_limit_reached';
+                        $status_code = 400;
+                } elseif ( $e instanceof InvalidArgumentException ) {
+                        $error_code  = 'prompt_invalid_argument';
+                        $status_code = 400;
+                } else {
+                        $error_code  = 'prompt_builder_error';
+                        $status_code = 500;
+                }
+
+                return new WP_Error(
+                        $error_code,
+                        $e->getMessage(),
+                        array(
+                                'status'          => $status_code,
+                                'exception_class' => get_class( $e ),
+                        )
+                );
         }