Merge pull request #7884 from MicrosoftDocs/jdaly-main-web-api-errors

AB#3578: Add Invalid Prefer request header value section

Author: lucciz01

support/power-platform/dataverse/dataverse-web-api-and-sdk/web-api-client-errors.md

@@ -1,7 +1,7 @@
 ---
 title: Troubleshoot Web API client errors
 description: Provides resolutions for the common client errors that occur when you use the Dataverse Web API.
-ms.date: 06/12/2024
+ms.date: 01/24/2024
 ms.custom: sap:Dataverse Web API and SDK\Odata endpoint errors
 author: divkamath
 ms.author: dikamath
@@ -45,13 +45,13 @@ HTTP/1.1 404 Not Found
 
 ### Cause
 
-This error occurs when you use the incorrect name for a resource. That resource might be the name of an entity set, a function or an action. These resource names are case sensitive. In the preceding example, there is an entity set called `accounts`, but not one named `Account`.
+This error occurs when you use the incorrect name for a resource. That resource might be the name of an entity set, a function, or an action. These resource names are case sensitive. In the preceding example, there's an entity set called `accounts`, but not one named `Account`.
 
 If the resource is an action defined as a [custom process action](/power-apps/developer/data-platform/workflow-custom-actions), this error can also happen if the custom process action is inactive.
 
 ### How to avoid
 
-- If the resource is an entity type, query the Web API [Service document](/power-apps/developer/data-platform/webapi/web-api-service-documents#service-document) which will provide a list of all the known entity set names.
+- If the resource is an entity type, query the Web API [Service document](/power-apps/developer/data-platform/webapi/web-api-service-documents#service-document) which provides a list of all the known entity set names.
 - If the resource is a function or action, verify that the name you use exists in the [CSDL $metadata document](/power-apps/developer/data-platform/webapi/web-api-service-documents#csdl-metadata-document).
 - If the action doesn't exist in the [CSDL $metadata document](/power-apps/developer/data-platform/webapi/web-api-service-documents#csdl-metadata-document), it might be an inactive [custom process action](/power-apps/developer/data-platform/workflow-custom-actions). You should verify that it's active.
 
@@ -82,7 +82,7 @@ HTTP/1.1 400 Bad Request
 
 This error occurs when you use the incorrect name for a property. Property names are case sensitive.
 
-In the preceding example, there is a property called `name`, but not one named `Name`.
+In the preceding example, there's a property called `name`, but not one named `Name`.
 
 ### How to avoid
 
@@ -113,11 +113,11 @@ HTTP/1.1 404 Not Found
 
 ### Cause
 
-This error occurs when the incorrect HTTP method is applied to a function or action. In this case, <xref:Microsoft.Dynamics.CRM.WhoAmI?text=WhoAmI Function> requires the use of `GET` but `POST` was used.
+This error occurs when the incorrect HTTP method is applied to a function or action. In this case, the [WhoAmI function](xref:Microsoft.Dynamics.CRM.WhoAmI) requires the use of `GET` but `POST` is used.
 
 ### How to avoid
 
-Be aware of what kind of OData operation you are using and the correct HTTP method to use. For more information, see:
+Be aware of what kind of OData operation you're using and the correct HTTP method to use. For more information, see:
 
 - [Web API Actions](/power-apps/developer/data-platform/webapi/web-api-actions)
 - [Use Web API actions](/power-apps/developer/data-platform/webapi/use-web-api-actions)
@@ -177,7 +177,7 @@ This error occurs when an invalid navigation property name is sent with a reques
 **Request**
 
 ```http
-POST [Organization URI]/api/data/v9.0/contacts HTTP/1.1
+POST [Organization URI]/api/data/v9.2/contacts HTTP/1.1
 
 {
   "firstname":"test",
@@ -205,9 +205,9 @@ HTTP/1.1 400 Bad Request
 
 #### Cause
 
-This error occurs because there is no single-valued navigation property in the contact entity type named `parentcustomerid`. For more information, see [contact EntityType > Single-valued navigation properties](/power-apps/developer/data-platform/webapi/reference/contact#single-valued-navigation-properties).
+This error occurs because there's no single-valued navigation property in the contact entity type named `parentcustomerid`. For more information, see [Single-valued navigation properties](/power-apps/developer/data-platform/webapi/reference/contact#single-valued-navigation-properties).
 
-`parentcustomerid` is the logical name of a lookup column in the contact table. All lookups are represented by single-valued navigation properties in OData. The names of the lookup properties don't always match the corresponding single-valued navigation property name.
+`parentcustomerid` is the logical name of a lookup column in the contact table. All lookups have one or more single-valued navigation properties in OData. The names of the lookup properties don't always match the corresponding single-valued navigation property name.
 
 In this case, the `parentcustomerid` column is a customer lookup type, a kind of [multi-table lookup](/power-apps/developer/data-platform/webapi/web-api-navigation-properties#multi-table-lookups) that might link to either the account or contact tables. To support this customer lookup, there are two separate relationships and each has a different single-valued navigation property. The correct single-valued navigation property in this case is `parentcustomerid_account`.
 
@@ -253,15 +253,15 @@ at System.Web.OData.Formatter.ODataMediaTypeFormatter.ReadFromStream(Type type,
 
 #### Cause
 
-This deserialization error is caused by the use of line endings other than [CRLF](https://developer.mozilla.org/docs/Glossary/CRLF) in the batch request body.
+The use of line endings other than [CRLF](https://developer.mozilla.org/docs/Glossary/CRLF) in the batch request body causes this deserialization error.
 
-Depending on the editor you use, these non-printing characters can be difficult to see . If you use [Notepad++](https://notepad-plus-plus.org/), you can use the **Show all characters** option to make these characters visible.
+Depending on the editor you use, these nonprinting characters can be difficult to see. If you use [Notepad++](https://notepad-plus-plus.org/), you can use the **Show all characters** option to make these characters visible.
 
-This payload will work:
+This payload works:
 
 :::image type="content" source="media/web-api-client-errors/batch-request-body-with-crlf-endings-for-all-lines.png" alt-text="Screenshot that shows a batch request body with CRLF endings for all lines.":::
 
-This payload will fail because the last line doesn't end with `CRLF`.
+This payload fails because the last line doesn't end with `CRLF`.
 
 :::image type="content" source="media/web-api-client-errors/batch-request-body-with-crlf-missing-last-line.png" alt-text="Screenshot that shows a batch request body with CRLF missing on the last line.":::
 
@@ -271,6 +271,48 @@ In this case, just adding a carriage return at the end of the last line is enoug
 
 Ensure all line endings in the `$batch` request body are `CRLF`. If you can't use `CRLF`, add two non-`CRLF` line endings at the end of the batch request body to resolve this deserialization error. For more information, see [Batch requests](/power-apps/developer/data-platform/webapi/execute-batch-operations-using-web-api#batch-requests).
 
+## Error identified on the 'odata.include-annotations' value inside the 'Prefer' header
+
+### Symptoms
+
+The error occurs when the [Dataverse Web API](/power-apps/developer/data-platform/webapi/overview) receives a request with an invalid `odata.include-annotations` value in the `Prefer` request header value. This issue occurs when the request is sent using the `POST`, `PATCH`, `PUT`, or `GET` HTTP methods with a `Prefer` request header that contains an invalid or improperly formatted value. 
+
+In the following example, the `odata.include-annotations` value incorrectly includes backslashes (\\) to escape the quote characters.
+
+**Request**
+
+```http
+POST [Organization URI]/api/data/v9.2/contacts HTTP/1.1
+
+Prefer: odata.include-annotations=\"*\"
+
+{
+  "firstname":"test",
+  "lastname":"contact"
+}
+```
+
+**Response**
+
+```http
+HTTP/1.1 400 Bad Request
+
+{
+  "Message": "Error identified on the 'odata.include-annotations' value inside the 'Prefer' header. 
+  Refer to the following link for more details: https://go.microsoft.com/fwlink/?linkid=2300109. 
+  See exception message for more details 'An error occurred when parsing the HTTP header 'Prefer'. The header value 'odata.include-annotations=\\\"*\\\"' is incorrect at position '26' because the escape character '\\' is not inside a quoted-string.'.",
+  "ErrorCode": "0x80097303"
+}
+```
+
+### Cause
+
+To provide a more secure service, we fix an issue where invalid `Prefer` request header values are processed without validation when using the `POST`, `PATCH`, or `PUT` HTTP methods. Now, validation is enforced for all HTTP methods. This error occurs starting with Dataverse version 9.2.2412.3 that begins deployment in January 2025 and will be deployed to all regions by February 2025.
+
+### How to avoid
+
+Review the guidance about how to properly set [Prefer headers in the Dataverse Web API](/power-apps/developer/data-platform/webapi/compose-http-requests-handle-errors#prefer-headers).
+
 ## See also
 
 - [Web API types and operations](/power-apps/developer/data-platform/webapi/web-api-types-operations)