docs: fix example in ResponseTrait::fail() (#9742)

Author: paulbalandan

system/API/ResponseTrait.php

@@ -122,9 +122,9 @@ protected function respond($data = null, ?int $status = null, string $message =
     /**
      * Used for generic failures that no custom methods exist for.
      *
-     * @param list<string>|string $messages
-     * @param int                 $status   HTTP status code
-     * @param string|null         $code     Custom, API-specific, error code
+     * @param array<array-key, string>|string $messages
+     * @param int                             $status   HTTP status code
+     * @param string|null                     $code     Custom, API-specific, error code
      *
      * @return ResponseInterface
      */
@@ -230,7 +230,7 @@ protected function failNotFound(string $description = 'Not Found', ?string $code
     /**
      * Used when the data provided by the client cannot be validated on one or more fields.
      *
-     * @param list<string>|string $errors
+     * @param array<array-key, string>|string $errors
      *
      * @return ResponseInterface
      */

user_guide_src/source/outgoing/api_responses.rst

@@ -116,8 +116,12 @@ Class Reference
     response status. Not every client will respect the custom codes, though, and will use the IANA standards
     that match the status code.
 
-    The response is an array with two elements: ``error`` and ``messages``. The ``error`` element contains the status
-    code of the error. The ``messages`` element contains an array of error messages. It would look something like:
+    The response is an array with three elements: ``status``, ``code``, and ``messages``.
+    - The ``status`` element contains the status code of the error.
+    - The ``code`` element contains a custom, API-specific error code.
+    - The ``messages`` element contains an array of error messages.
+
+    Depending on the number of error messages, the response would look something like:
 
     .. literalinclude:: api_responses/006.php
 

user_guide_src/source/outgoing/api_responses/006.php

@@ -1,10 +1,20 @@
 <?php
 
+// Example response with a single error message
+$response = [
+    'status'   => 400,
+    'code'     => '321',
+    'messages' => [
+        'error' => 'An error occurred',
+    ],
+];
+
+// Example response with multiple error messages per field
 $response = [
     'status'   => 400,
     'code'     => '321a',
     'messages' => [
-        'Error message 1',
-        'Error message 2',
+        'foo' => 'Error message 1',
+        'bar' => 'Error message 2',
     ],
 ];