Use original error message if provided

src/Serializer/AbstractItemNormalizer.php

@@ -26,6 +26,7 @@
 use ApiPlatform\Metadata\UrlGeneratorInterface;
 use ApiPlatform\Metadata\Util\ClassInfoTrait;
 use ApiPlatform\Metadata\Util\CloneTrait;
+use ApiPlatform\Serializer\Exception\CustomUserMessageNotNormalizableValueException;
 use Symfony\Component\PropertyAccess\Exception\NoSuchPropertyException;
 use Symfony\Component\PropertyAccess\PropertyAccess;
 use Symfony\Component\PropertyAccess\PropertyAccessorInterface;
@@ -203,7 +204,12 @@ public function denormalize(mixed $data, string $class, ?string $format = null,
             try {
                 return $this->serializer->denormalize($data, $inputClass, $format, $context);
             } catch (NotNormalizableValueException $e) {
-                throw new UnexpectedValueException('The input data is misformatted.', $e->getCode(), $e);
+                $originalMessage = $e->getMessage();
+                $newMessage = '' !== $originalMessage
+                    ? \sprintf('The input data is misformatted: %s', $originalMessage)
+                    : 'The input data is misformatted.';
+
+                throw new UnexpectedValueException($newMessage, $e->getCode(), $e);
             }
         }
 
@@ -322,7 +328,7 @@ protected function instantiateObject(array &$data, string $class, array &$contex
                     try {
                         $params[] = $this->createConstructorArgument($data[$key], $key, $constructorParameter, $attributeContext, $format);
                     } catch (NotNormalizableValueException $exception) {
-                        if (!isset($context['not_normalizable_value_exceptions'])) {
+                        if (!isset($context['not_normalizable_value_exceptions']) && !$exception instanceof CustomUserMessageNotNormalizableValueException) {
                             throw $exception;
                         }
                         $context['not_normalizable_value_exceptions'][] = $exception;
@@ -501,7 +507,7 @@ protected function setAttributeValue(object $object, string $attribute, mixed $v
             $this->setValue($object, $attribute, $this->createAttributeValue($attribute, $value, $format, $context));
         } catch (NotNormalizableValueException $exception) {
             // Only throw if collecting denormalization errors is disabled.
-            if (!isset($context['not_normalizable_value_exceptions'])) {
+            if (!isset($context['not_normalizable_value_exceptions']) && !$exception instanceof CustomUserMessageNotNormalizableValueException) {
                 throw $exception;
             }
         }
@@ -854,7 +860,7 @@ private function createAttributeValue(string $attribute, mixed $value, ?string $
         try {
             return $this->createAndValidateAttributeValue($attribute, $value, $format, $context);
         } catch (NotNormalizableValueException $exception) {
-            if (!isset($context['not_normalizable_value_exceptions'])) {
+            if (!isset($context['not_normalizable_value_exceptions']) && !$exception instanceof CustomUserMessageNotNormalizableValueException) {
                 throw $exception;
             }
             $context['not_normalizable_value_exceptions'][] = $exception;

src/Serializer/Exception/CustomUserMessageNotNormalizableValueException.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace ApiPlatform\Serializer\Exception;
+
+use Symfony\Component\Serializer\Exception\NotNormalizableValueException;
+
+class CustomUserMessageNotNormalizableValueException extends NotNormalizableValueException
+{
+    private string $messageKey;
+    private array $messageData = [];
+
+    public function __construct(string $message = '', array $messageData = [], int $code = 0, ?\Throwable $previous = null)
+    {
+        parent::__construct($message, $code, $previous);
+
+        $this->setSafeMessage($message, $messageData);
+    }
+
+    /**
+     * Set a message that will be shown to the user.
+     *
+     * @param string $messageKey  The message or message key
+     * @param array  $messageData Data to be passed into the translator
+     */
+    public function setSafeMessage(string $messageKey, array $messageData = []): void
+    {
+        $this->messageKey = $messageKey;
+        $this->messageData = $messageData;
+    }
+
+    public function getMessageKey(): string
+    {
+        return $this->messageKey;
+    }
+
+    public function getMessageData(): array
+    {
+        return $this->messageData;
+    }
+}

src/State/Provider/DeserializeProvider.php

@@ -15,6 +15,7 @@
 
 use ApiPlatform\Metadata\HttpOperation;
 use ApiPlatform\Metadata\Operation;
+use ApiPlatform\Serializer\Exception\CustomUserMessageNotNormalizableValueException;
 use ApiPlatform\State\ProviderInterface;
 use ApiPlatform\State\SerializerContextBuilderInterface;
 use ApiPlatform\Validator\Exception\ValidationException;
@@ -97,6 +98,14 @@
 
             $violations = new ConstraintViolationList();
             foreach ($e->getErrors() as $exception) {
+                if ($exception instanceof CustomUserMessageNotNormalizableValueException) {
+                    $message = $exception->getMessageKey();
+                    $parameters = $exception->getMessageData();
+
+                    $violations->add(new ConstraintViolation($this->translator->trans($message, $parameters, 'validators'), $message, $parameters, null, $exception->getPath()));
+                    continue;
+                }
+
                 if (!$exception instanceof NotNormalizableValueException) {
                     continue;
                 }