fix(serializer): fix union types denormalization fallback after security mismatch

src/Serializer/AbstractItemNormalizer.php

@@ -766,7 +766,7 @@ private function getResourceFromIri(string $data, array $context, string $resour
 
             // Type-confusion guard: declared relation class must match the IRI's resource.
             if (!is_a($item, $resourceClass)) {
-                throw new InvalidArgumentException(\sprintf('The iri "%s" does not reference the correct resource.', $data));
+                throw new NotNormalizableValueException(\sprintf('The iri "%s" does not reference the correct resource.', $data));
             }
 
             return $item;

src/Serializer/Tests/AbstractItemNormalizerTest.php

@@ -1238,6 +1238,53 @@ public function testDenormalizeWritableLinks(): void
         $propertyAccessorProphecy->setValue($actual, 'relatedDummiesWithUnionTypes', [0 => $relatedDummy3, 1 => $relatedDummy4])->shouldHaveBeenCalled();
     }
 
+    public function testUnionTypeDenormalizationFallsThroughAfterTypeConfusionGuardMismatch(): void
+    {
+        $data = ['relatedDummyUnion' => '/related_dummies/1'];
+        $relatedDummy = new RelatedDummy();
+
+        $propertyNameCollectionFactory = $this->createStub(PropertyNameCollectionFactoryInterface::class);
+        $propertyNameCollectionFactory->method('create')->willReturn(new PropertyNameCollection(['relatedDummyUnion']));
+
+        // Dummy is the mismatching member tried first; RelatedDummy is the one that actually matches.
+        $propertyMetadataFactory = $this->createStub(PropertyMetadataFactoryInterface::class);
+        $propertyMetadataFactory->method('create')->willReturn(
+            (new ApiProperty())
+                ->withNativeType(Type::union(Type::object(Dummy::class), Type::object(RelatedDummy::class)))
+                ->withWritable(true)->withWritableLink(true)
+        );
+
+        // Always resolves to a RelatedDummy, no matter which type of the union is being attempted.
+        $iriConverter = $this->createStub(IriConverterInterface::class);
+        $iriConverter->method('getResourceFromIri')->willReturn($relatedDummy);
+
+        $resourceClassResolver = $this->createStub(ResourceClassResolverInterface::class);
+        $resourceClassResolver->method('isResourceClass')->willReturnMap([
+            [Dummy::class, true],
+            [RelatedDummy::class, true],
+        ]);
+        $resourceClassResolver->method('getResourceClass')->willReturnMap([
+            [null, Dummy::class, Dummy::class],
+            [null, RelatedDummy::class, RelatedDummy::class],
+        ]);
+
+        $propertyAccessor = $this->createMock(PropertyAccessorInterface::class);
+        $propertyAccessor->expects($this->once())
+            ->method('setValue')
+            ->with($this->isInstanceOf(Dummy::class), 'relatedDummyUnion', $relatedDummy);
+
+        $serializer = $this->createStub(SerializerInterface::class);
+
+        $normalizer = new class($propertyNameCollectionFactory, $propertyMetadataFactory, $iriConverter, $resourceClassResolver, $propertyAccessor, null, null, [], null, null) extends AbstractItemNormalizer {};
+        $normalizer->setSerializer($serializer);
+
+        // The first union member (Dummy) should correctly fail and we expect to fallback to the second
+        // member (RelatedDummy).
+        $actual = $normalizer->denormalize($data, Dummy::class);
+
+        $this->assertInstanceOf(Dummy::class, $actual);
+    }
+
     public function testDenormalizeRelationNotFoundReturnsNull(): void
     {
         $data = [