Add tests to validate 404/1003 substatus code distinction

Co-authored-by: kirankumarkolli <6880899+kirankumarkolli@users.noreply.github.com>

Author: Copilot

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.EmulatorTests/CosmosNotFoundTests.cs

@@ -97,6 +97,115 @@ public async Task ValidateQueryNotFoundResponse()
             await db.DeleteAsync();
         }
 
+        /// <summary>
+        /// Validates that 404 with substatus 0 is returned when an item doesn't exist,
+        /// and 404 with substatus 1003 is returned when the container doesn't exist.
+        /// This allows disambiguation between item not found vs owner resource (container/database) not found.
+        /// </summary>
+        [TestMethod]
+        public async Task ValidateSubStatusCodeForItemNotFoundVsContainerNotFound()
+        {
+            // Create a test database and container
+            Database db = await CosmosNotFoundTests.client.CreateDatabaseAsync("NotFoundTest" + Guid.NewGuid().ToString());
+            Container container = await db.CreateContainerAsync("NotFoundTest" + Guid.NewGuid().ToString(), "/pk", 500);
+
+            // Test 1: Item doesn't exist in existing container - should return 404 with substatus 0
+            ResponseMessage response = await container.ReadItemStreamAsync(
+                partitionKey: new Cosmos.PartitionKey(DoesNotExist), 
+                id: DoesNotExist);
+            
+            Assert.IsNotNull(response);
+            Assert.AreEqual(HttpStatusCode.NotFound, response.StatusCode);
+            Assert.AreEqual(0, (int)response.Headers.SubStatusCode, 
+                "SubStatusCode should be 0 when item doesn't exist in an existing container");
+
+            // Test 2: Container doesn't exist - should return 404 with substatus 1003
+            Container nonExistentContainer = db.GetContainer(DoesNotExist);
+            response = await nonExistentContainer.ReadItemStreamAsync(
+                partitionKey: new Cosmos.PartitionKey(DoesNotExist), 
+                id: DoesNotExist);
+            
+            Assert.IsNotNull(response);
+            Assert.AreEqual(HttpStatusCode.NotFound, response.StatusCode);
+            Assert.AreEqual(1003, (int)response.Headers.SubStatusCode, 
+                "SubStatusCode should be 1003 when container doesn't exist (owner resource not found)");
+
+            // Test 3: Database doesn't exist - should also return 404 with substatus 1003
+            Database nonExistentDb = CosmosNotFoundTests.client.GetDatabase(DoesNotExist);
+            Container containerInNonExistentDb = nonExistentDb.GetContainer(DoesNotExist);
+            response = await containerInNonExistentDb.ReadItemStreamAsync(
+                partitionKey: new Cosmos.PartitionKey(DoesNotExist), 
+                id: DoesNotExist);
+            
+            Assert.IsNotNull(response);
+            Assert.AreEqual(HttpStatusCode.NotFound, response.StatusCode);
+            Assert.AreEqual(1003, (int)response.Headers.SubStatusCode, 
+                "SubStatusCode should be 1003 when database doesn't exist (owner resource not found)");
+
+            // Cleanup
+            await db.DeleteAsync();
+        }
+
+        /// <summary>
+        /// Validates that CosmosException exposes the substatus code when thrown,
+        /// allowing developers to distinguish between different types of 404 errors.
+        /// </summary>
+        [TestMethod]
+        public async Task ValidateCosmosExceptionSubStatusCodeForNotFound()
+        {
+            // Create a test database and container
+            Database db = await CosmosNotFoundTests.client.CreateDatabaseAsync("NotFoundTest" + Guid.NewGuid().ToString());
+            Container container = await db.CreateContainerAsync("NotFoundTest" + Guid.NewGuid().ToString(), "/pk", 500);
+
+            // Test 1: Item doesn't exist in existing container - CosmosException should have substatus 0
+            try
+            {
+                ItemResponse<dynamic> response = await container.ReadItemAsync<dynamic>(
+                    partitionKey: new Cosmos.PartitionKey(DoesNotExist),
+                    id: DoesNotExist);
+                Assert.Fail("Expected CosmosException to be thrown");
+            }
+            catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+            {
+                Assert.AreEqual(0, ex.SubStatusCode, 
+                    "SubStatusCode should be 0 when item doesn't exist in an existing container");
+            }
+
+            // Test 2: Container doesn't exist - CosmosException should have substatus 1003
+            Container nonExistentContainer = db.GetContainer(DoesNotExist);
+            try
+            {
+                ItemResponse<dynamic> response = await nonExistentContainer.ReadItemAsync<dynamic>(
+                    partitionKey: new Cosmos.PartitionKey(DoesNotExist),
+                    id: DoesNotExist);
+                Assert.Fail("Expected CosmosException to be thrown");
+            }
+            catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+            {
+                Assert.AreEqual(1003, ex.SubStatusCode, 
+                    "SubStatusCode should be 1003 when container doesn't exist (owner resource not found)");
+            }
+
+            // Test 3: Database doesn't exist - CosmosException should have substatus 1003
+            Database nonExistentDb = CosmosNotFoundTests.client.GetDatabase(DoesNotExist);
+            Container containerInNonExistentDb = nonExistentDb.GetContainer(DoesNotExist);
+            try
+            {
+                ItemResponse<dynamic> response = await containerInNonExistentDb.ReadItemAsync<dynamic>(
+                    partitionKey: new Cosmos.PartitionKey(DoesNotExist),
+                    id: DoesNotExist);
+                Assert.Fail("Expected CosmosException to be thrown");
+            }
+            catch (CosmosException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
+            {
+                Assert.AreEqual(1003, ex.SubStatusCode, 
+                    "SubStatusCode should be 1003 when database doesn't exist (owner resource not found)");
+            }
+
+            // Cleanup
+            await db.DeleteAsync();
+        }
+
         private async Task ContainerOperations(Database database, bool dbNotExist)
         {
             // Create should fail if the database does not exist

Microsoft.Azure.Cosmos/tests/Microsoft.Azure.Cosmos.Tests/CosmosExceptionTests.cs

@@ -457,6 +457,108 @@ public void GenerateEventWithDiagnosticWithFilterOnStatusCodeTest()
             }
         }
 
+        /// <summary>
+        /// Validates that substatus code 1003 (OwnerResourceNotFound) can be used to distinguish
+        /// between a regular 404 (item not found) and a 404 where the parent resource doesn't exist.
+        /// </summary>
+        [TestMethod]
+        public void ValidateSubStatusCode1003ForOwnerResourceNotFound()
+        {
+            // Test creating a NotFoundException with substatus code 1003
+            string testMessage = "Owner resource not found";
+            string activityId = Guid.NewGuid().ToString();
+            int ownerNotFoundSubStatus = 1003; // SubStatusCodes.OwnerResourceNotFound
+            double requestCharge = 1.0;
+
+            CosmosException exception = CosmosExceptionFactory.CreateNotFoundException(
+                testMessage,
+                new Headers()
+                {
+                    SubStatusCodeLiteral = ownerNotFoundSubStatus.ToString(),
+                    ActivityId = activityId,
+                    RequestCharge = requestCharge
+                });
+
+            Assert.AreEqual(HttpStatusCode.NotFound, exception.StatusCode);
+            Assert.AreEqual(ownerNotFoundSubStatus, exception.SubStatusCode);
+            Assert.AreEqual(ownerNotFoundSubStatus.ToString(), exception.Headers.SubStatusCodeLiteral);
+            Assert.AreEqual(testMessage, exception.ResponseBody);
+            Assert.AreEqual(activityId, exception.ActivityId);
+            Assert.AreEqual(requestCharge, exception.RequestCharge);
+
+            // Verify the exception message contains all the relevant information
+            Assert.IsTrue(exception.Message.Contains("404"));
+            Assert.IsTrue(exception.Message.Contains("1003"));
+            Assert.IsTrue(exception.ToString().Contains(testMessage));
+        }
+
+        /// <summary>
+        /// Validates that substatus code 0 distinguishes a regular item not found from owner not found.
+        /// </summary>
+        [TestMethod]
+        public void ValidateSubStatusCode0ForRegularItemNotFound()
+        {
+            // Test creating a NotFoundException with substatus code 0 (regular item not found)
+            string testMessage = "Item not found";
+            string activityId = Guid.NewGuid().ToString();
+            int itemNotFoundSubStatus = 0;
+            double requestCharge = 1.0;
+
+            CosmosException exception = CosmosExceptionFactory.CreateNotFoundException(
+                testMessage,
+                new Headers()
+                {
+                    SubStatusCodeLiteral = itemNotFoundSubStatus.ToString(),
+                    ActivityId = activityId,
+                    RequestCharge = requestCharge
+                });
+
+            Assert.AreEqual(HttpStatusCode.NotFound, exception.StatusCode);
+            Assert.AreEqual(itemNotFoundSubStatus, exception.SubStatusCode);
+            Assert.AreEqual(itemNotFoundSubStatus.ToString(), exception.Headers.SubStatusCodeLiteral);
+            Assert.AreEqual(testMessage, exception.ResponseBody);
+            Assert.AreEqual(activityId, exception.ActivityId);
+            Assert.AreEqual(requestCharge, exception.RequestCharge);
+
+            // Verify the exception message contains all the relevant information
+            Assert.IsTrue(exception.Message.Contains("404"));
+            Assert.IsTrue(exception.Message.Contains("0"));
+            Assert.IsTrue(exception.ToString().Contains(testMessage));
+        }
+
+        /// <summary>
+        /// Validates that ResponseMessage correctly exposes substatus codes for 404 errors.
+        /// </summary>
+        [TestMethod]
+        public void ValidateResponseMessageSubStatusCodeForNotFound()
+        {
+            // Create ResponseMessage with 404 and substatus 0 (item not found)
+            Headers headersItemNotFound = new Headers()
+            {
+                SubStatusCodeLiteral = "0",
+                ActivityId = Guid.NewGuid().ToString()
+            };
+
+            ResponseMessage responseItemNotFound = new ResponseMessage(HttpStatusCode.NotFound)
+            {
+                Headers = { }
+            };
+            responseItemNotFound.Headers.SubStatusCodeLiteral = "0";
+
+            Assert.AreEqual(HttpStatusCode.NotFound, responseItemNotFound.StatusCode);
+            Assert.AreEqual(0, (int)responseItemNotFound.Headers.SubStatusCode);
+
+            // Create ResponseMessage with 404 and substatus 1003 (owner resource not found)
+            ResponseMessage responseOwnerNotFound = new ResponseMessage(HttpStatusCode.NotFound)
+            {
+                Headers = { }
+            };
+            responseOwnerNotFound.Headers.SubStatusCodeLiteral = "1003";
+
+            Assert.AreEqual(HttpStatusCode.NotFound, responseOwnerNotFound.StatusCode);
+            Assert.AreEqual(1003, (int)responseOwnerNotFound.Headers.SubStatusCode);
+        }
+
         private void ValidateExceptionInfo(
             CosmosException exception,
             HttpStatusCode httpStatusCode,