Merge pull request #1993 from MicrosoftDocs/atp-api-update-feb20

Add troubleshooting paper

windows/security/threat-protection/TOC.md

@@ -384,6 +384,7 @@
 
 ##### [Microsoft Defender ATP APIs Schema]()
 ###### [Supported Microsoft Defender ATP APIs](microsoft-defender-atp/exposed-apis-list.md)
+###### [Common REST API error codes](microsoft-defender-atp/common-errors.md)
 ###### [Advanced Hunting](microsoft-defender-atp/run-advanced-query-api.md)
 
 ###### [Alert]()
@@ -461,7 +462,7 @@
 ####### [Score methods and properties](microsoft-defender-atp/score.md)
 ####### [List exposure score by machine group](microsoft-defender-atp/get-machine-group-exposure-score.md)
 ####### [Get exposure score](microsoft-defender-atp/get-exposure-score.md)
-####### [Get device secure score](microsoft-defender-atp/get-device-secure-score.md)
+####### [Get machine secure score](microsoft-defender-atp/get-device-secure-score.md)
 
 ###### [Software]()
 ####### [Software methods and properties](microsoft-defender-atp/software.md)
@@ -473,7 +474,7 @@
 
 ###### [Vulnerability]()
 ####### [Vulnerability methods and properties](microsoft-defender-atp/vulnerability.md)
-####### [Get all vulnerabilities](microsoft-defender-atp/get-all-vulnerabilities.md)
+####### [List vulnerabilities](microsoft-defender-atp/get-all-vulnerabilities.md)
 ####### [Get vulnerability by Id](microsoft-defender-atp/get-vulnerability-by-id.md)
 ####### [List machines by vulnerability](microsoft-defender-atp/get-machines-by-vulnerability.md)
 
@@ -482,8 +483,8 @@
 ####### [List all recommendations](microsoft-defender-atp/get-all-recommendations.md)
 ####### [Get recommendation by Id](microsoft-defender-atp/get-recommendation-by-id.md)
 ####### [Get recommendation by software](microsoft-defender-atp/get-recommendation-software.md)
-####### [Get recommendation by machines](microsoft-defender-atp/get-recommendation-machines.md)
+####### [List machines by recommendation](microsoft-defender-atp/get-recommendation-machines.md)
-####### [Get recommendation by vulnerabilities](microsoft-defender-atp/get-recommendation-vulnerabilities.md)
+####### [List vulnerabilities by recommendation](microsoft-defender-atp/get-recommendation-vulnerabilities.md)
 
 ##### [How to use APIs - Samples]()
 ###### [Microsoft Flow](microsoft-defender-atp/api-microsoft-flow.md)

windows/security/threat-protection/microsoft-defender-atp/common-errors.md

@@ -0,0 +1,83 @@
+---
+title: Common Microsoft Defender ATP API errors
+description: List of common Microsoft Defender ATP API errors with descriptions.
+keywords: apis, mdatp api, errors, troubleshooting 
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+manager: dansimp
+audience: ITPro
+ms.collection: M365-security-compliance 
+ms.topic: article
+---
+
+# Common REST API error codes
+
+* The error codes listed in the following table may be returned by an operation on any of Microsoft Defender ATP APIs.
+* Note that in addition to the error code, every error response contains an error message which can help resolving the problem.
+* Note that the message is a free text that can be changed.
+* At the bottom of the page you can find response examples.
+
+Error code |HTTP status code |Message 
+:---|:---|:---
+BadRequest | BadRequest (400) | General Bad Request error message.
+ODataError | BadRequest (400) | Invalid OData URI query (the specific error is specified).
+InvalidInput | BadRequest (400) | Invalid input {the invalid input}.
+InvalidRequestBody | BadRequest (400) | Invalid request body.
+InvalidHashValue | BadRequest (400) | Hash value {the invalid hash} is invalid.
+InvalidDomainName | BadRequest (400) | Domain name {the invalid domain} is invalid.
+InvalidIpAddress | BadRequest (400) | IP address {the invalid IP} is invalid.
+InvalidUrl | BadRequest (400) | URL {the invalid URL} is invalid.
+MaximumBatchSizeExceeded | BadRequest (400) | Maximum batch size exceeded. Received: {batch size received}, allowed: {batch size allowed}.
+MissingRequiredParameter | BadRequest (400) | Parameter {the missing parameter} is missing.
+OsPlatformNotSupported | BadRequest (400) | OS Platform {the client OS Platform} is not supported for this action.
+ClientVersionNotSupported | BadRequest (400) | {The requested action} is supported on client version {supported client version} and above.
+Unauthorized | Unauthorized (401) | Unauthorized (usually invalid or expired authorization header).
+Forbidden | Forbidden (403) | Forbidden (valid token but insufficient permission for the action).
+DisabledFeature | Forbidden (403) | Tenant feature is not enabled.
+DisallowedOperation | Forbidden (403) | {the disallowed operation and the reason}.
+NotFound | Not Found (404) | General Not Found error message.
+ResourceNotFound | Not Found (404) | Resource {the requested resource} was not found.
+InternalServerError | Internal Server Error (500) | (No error message, try retry the operation or contact us if it does not resolved)
+
+## Body parameters are case sensitive
+
+The submitted body parameters are currently case sensitive.
+<br>If you experience an **InvalidRequestBody** or **MissingRequiredParameter** errors, it might be caused from a wrong parameter capital or lower-case letter.
+<br>It is recommended to go to the requested Api documentation page and check that the submitted parameters match the relevant example.
+
+## Correlation request ID
+
+Each error response contains a unique ID parameter for tracking.
+<br>The property name of this parameter is "target".
+<br>When contacting us about an error, attaching this ID will help find the root cause of the problem.
+
+## Examples
+
+```json
+{
+    "error": {
+        "code": "ResourceNotFound",
+        "message": "Machine 123123123 was not found",
+        "target": "43f4cb08-8fac-4b65-9db1-745c2ae65f3a"
+    }
+}
+```
+
+
+```json
+{
+    "error": {
+        "code": "InvalidRequestBody",
+        "message": "Request body is incorrect",
+        "target": "1fa66c0f-18bd-4133-b378-36d76f3a2ba0"
+    }
+}
+```
+
+

windows/security/threat-protection/microsoft-defender-atp/get-all-recommendations.md

@@ -66,8 +66,7 @@ GET https://api.securitycenter.windows.com/api/recommendations
 Here is an example of the response.
 
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Recommendations",
     "value": [
@@ -99,6 +98,7 @@ Content-type: json
             "nonProductivityImpactedAssets": 0,
             "relatedComponent": "Windows 10"
         }
+		...
      ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-all-vulnerabilities.md

@@ -16,7 +16,7 @@ ms.collection: M365-security-compliance
 ms.topic: article
 ---
 
-# Get all vulnerabilities
+# List vulnerabilities
 **Applies to:**
 - [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
@@ -66,8 +66,7 @@ GET https://api.securitycenter.windows.com/api/Vulnerabilities
 Here is an example of the response.
 
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#Vulnerabilities",
     "value": [
@@ -86,8 +85,9 @@ Content-type: json
             "exploitTypes": [],
             "exploitUris": []
         }
+		...
     ]
-        {
+
 }
 ```
 

windows/security/threat-protection/microsoft-defender-atp/get-device-secure-score.md

@@ -1,6 +1,6 @@
 ---
-title: Get Device Secure score
+title: Get Machine Secure score
-description: Retrieves the organizational device secure score.
+description: Retrieves the organizational machine secure score.
 keywords: apis, graph api, supported apis, get, alerts, recent
 search.product: eADQiWindows 10XVcnh
 ms.prod: w10
@@ -16,7 +16,7 @@ ms.collection: M365-security-compliance
 ms.topic: article
 ---
 
-# Get Device Secure score
+# Get Machine Secure score
 
 **Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
@@ -75,8 +75,7 @@ Here is an example of the response.
 {
     "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ConfigurationScore/$entity",
     "time": "2019-12-03T09:15:58.1665846Z",
-    "score": 340,
+    "score": 340
-    "rbacGroupId": null
 }
 ```
 

windows/security/threat-protection/microsoft-defender-atp/get-exposure-score.md

@@ -76,8 +76,7 @@ Here is an example of the response.
 {
     "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ExposureScore/$entity",
     "time": "2019-12-03T07:23:53.280499Z",
-    "score": 33.491554051195706,
+    "score": 33.491554051195706
-    "rbacGroupId": null
 }
 
 ```

windows/security/threat-protection/microsoft-defender-atp/get-machine-group-exposure-score.md

@@ -18,9 +18,9 @@ ms.topic: article
 
 # List exposure score by machine group
 
-**Applies to:**
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
 
 [!include[Prerelease information](../../includes/prerelease.md)]
 
@@ -74,23 +74,14 @@ Here is an example of the response.
         {
             "time": "2019-12-03T09:51:28.214338Z",
             "score": 41.38041766305988,
-            "rbacGroupId": 10
+            "rbacGroupName": "GroupOne"
         },
         {
             "time": "2019-12-03T09:51:28.2143399Z",
             "score": 37.403726933165366,
-            "rbacGroupId": 11
+            "rbacGroupName": "GroupTwo"
-        },
-        {
-            "time": "2019-12-03T09:51:28.2143407Z",
-            "score": 26.390921344426033,
-            "rbacGroupId": 9
-        },
-        {
-            "time": "2019-12-03T09:51:28.2143414Z",
-            "score": 23.58823563070858,
-            "rbacGroupId": 5
         }
+		...
     ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-machines-by-software.md

@@ -24,7 +24,7 @@ ms.topic: article
 
 [!include[Prerelease information](../../includes/prerelease.md)]
 
-Retrieve a list of machines that has this software installed.
+Retrieve a list of machine references that has this software installed.
 
 ## Permissions
 One of the following permissions is required to call this API. To learn more, including how to choose permissions, see [Use Microsoft Defender ATP APIs](apis-intro.md) for details.
@@ -75,15 +75,16 @@ Here is an example of the response.
             "id": "7c7e1896fa39efb0a32a2cf421d837af1b9bf762",
             "computerDnsName": "dave_desktop",
             "osPlatform": "Windows10",
-            "rbacGroupId": 9
+            "rbacGroupName": "GroupTwo"
         },
         {
             "id": "7d5cc2e7c305e4a0a290392abf6707f9888fda0d",
             "computerDnsName": "jane_PC",
             "osPlatform": "Windows10",
-            "rbacGroupId": 9
+            "rbacGroupName": "GroupTwo"
         }
-]
+		...
+	]
 }
 ```
 

windows/security/threat-protection/microsoft-defender-atp/get-machines-by-vulnerability.md

@@ -66,8 +66,7 @@ GET https://api.securitycenter.windows.com/api/vulnerabilities/CVE-2019-0608/mac
 Here is an example of the response.
 
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#MachineReferences",
     "value": [
@@ -75,14 +74,15 @@ Content-type: json
             "id": "235a2e6278c63fcf85bab9c370396972c58843de",
             "computerDnsName": "h1mkn_PC",
             "osPlatform": "Windows10",
-            "rbacGroupId": 1268
+            "rbacGroupName": "GroupTwo"
         },
         {
             "id": "afb3f807d1a185ac66668f493af028385bfca184",
             "computerDnsName": "chat_Desk ",
             "osPlatform": "Windows10",
-            "rbacGroupId": 410
+            "rbacGroupName": "GroupTwo"
         }
+		...
     ]
  }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-recommendation-by-id.md

@@ -65,8 +65,7 @@ GET https://api.securitycenter.windows.com/api/recommendations/va-_-google-_-chr
 
 Here is an example of the response.
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Recommendations/$entity",
     "id": "va-_-google-_-chrome",

windows/security/threat-protection/microsoft-defender-atp/get-recommendation-machines.md

@@ -1,5 +1,5 @@
 ---
-title: Get recommendation by machines
+title: List machines by recommendation
 description: Retrieves a list of machines associated with the security recommendation. 
 keywords: apis, graph api, supported apis, get, security recommendation for vulnerable machines, threat and vulnerability management, threat and vulnerability management api 
 search.product: eADQiWindows 10XVcnh
@@ -16,7 +16,7 @@ ms.collection: M365-security-compliance
 ms.topic: article
 ---
 
-# Get recommendation by machines
+# List machines by recommendation
 **Applies to:**
 - [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
@@ -75,6 +75,7 @@ Here is an example of the response.
             "osPlatform": "Windows10",
             "rbacGroupId": 2154
         }
+		...
     ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-recommendation-software.md

@@ -65,8 +65,7 @@ GET https://api.securitycenter.windows.com/api/recommendations/va-_-google-_-chr
 
 Here is an example of the response.
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Analytics.Contracts.PublicAPI.PublicProductDto",
     "id": "google-_-chrome",

windows/security/threat-protection/microsoft-defender-atp/get-recommendation-vulnerabilities.md

@@ -1,5 +1,5 @@
 ---
-title: Get recommendation by vulnerabilities
+title: List vulnerabilities by recommendation
 description: Retrieves a list of vulnerabilities associated with the security recommendation.
 keywords: apis, graph api, supported apis, get, list of vulnerabilities, security recommendation, security recommendation for vulnerabilities, threat and vulnerability management, threat and vulnerability management api 
 search.product: eADQiWindows 10XVcnh
@@ -16,7 +16,7 @@ ms.collection: M365-security-compliance
 ms.topic: article
 ---
 
-# Get recommendation by vulnerabilities
+# List vulnerabilities by recommendation
 **Applies to:**
 - [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
@@ -65,8 +65,7 @@ GET https://api.securitycenter.windows.com/api/recommendations/va-_-google-_-chr
 
 Here is an example of the response.
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api.securitycenter.windows.com/api/$metadata#Collection(Analytics.Contracts.PublicAPI.PublicVulnerabilityDto)",
     "value": [
@@ -85,6 +84,7 @@ Content-type: json
             "exploitTypes": [],
             "exploitUris": []
         }
+		...
      ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-software-ver-distribution.md

@@ -81,6 +81,7 @@ Here is an example of the response.
             "installations": 750,
             "vulnerabilities": 0
         }
+		...
     ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-software.md

@@ -17,10 +17,10 @@ ms.topic: article
 ---
 
 # List software inventory API
-**Applies to:**
-- [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
 
-[!include[Prerelease information](../../includes/prerelease.md)]
+**Applies to:** [Microsoft Defender Advanced Threat Protection (Microsoft Defender ATP)](https://go.microsoft.com/fwlink/p/?linkid=2069559)
+
+- Want to experience Microsoft Defender ATP? [Sign up for a free trial.](https://www.microsoft.com/microsoft-365/windows/microsoft-defender-atp?ocid=docs-wdatp-exposedapis-abovefoldlink) 
 
 Retrieves the organization software inventory.
 
@@ -66,7 +66,7 @@ GET https://api.securitycenter.windows.com/api/Software
 Here is an example of the response.
 
 
-```
+```json
 {
     "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#Software",
     "value": [
@@ -80,6 +80,7 @@ Here is an example of the response.
 				"exposedMachines": 172,
 				"impactScore": 2.39947438
 			}
+			...
         ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-vuln-by-software.md

@@ -86,6 +86,7 @@ Here is an example of the response.
 				"exploitTypes": [],
 				"exploitUris": []
 			}
+			...
         ]
 }
 ```

windows/security/threat-protection/microsoft-defender-atp/get-vulnerability-by-id.md

@@ -65,8 +65,7 @@ GET https://api.securitycenter.windows.com/api/Vulnerabilities/CVE-2019-0608
 
 Here is an example of the response.
 
-```
+```json
-Content-type: json
 {
     "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#Vulnerabilities/$entity",
     "id": "CVE-2019-0608",

windows/security/threat-protection/microsoft-defender-atp/oldTOC.txt

@@ -345,6 +345,7 @@
 
 ##### [APIs]()
 ###### [Supported Microsoft Defender ATP APIs](exposed-apis-list.md)
+###### [Common REST API error codes](common-errors.md)
 ###### [Advanced Hunting](run-advanced-query-api.md)
 
 ###### [Alert]()

windows/security/threat-protection/microsoft-defender-atp/score.md

@@ -37,41 +37,4 @@ Property |	Type	|	Description
 :---|:---|:---
 Score | Double | The current score.
 Time | DateTime | The date and time in which the call for this API was made.
-RbacGroupId | Nullable Int | RBAC Group ID.
+RbacGroupName | String | The machine group name.
-
-
-### Response example for getting machine groups score:
-
-```
-GET https://api.securitycenter.windows.com/api/exposureScore/byMachineGroups
-```
-
-```json
-{
-    "@odata.context": "https://api-us.securitycenter.windows.com/api/$metadata#ExposureScore",
-    "value": [
-        {
-            "time": "2019-12-03T07:26:49.9376328Z",
-            "score": 41.38041766305988,
-            "rbacGroupId": 10
-        },
-        {
-            "time": "2019-12-03T07:26:49.9376375Z",
-            "score": 23.58823563070858,
-            "rbacGroupId": 5
-        },
-        {
-            "time": "2019-12-03T07:26:49.9376382Z",
-            "score": 37.403726933165366,
-            "rbacGroupId": 11
-        },
-        {
-            "time": "2019-12-03T07:26:49.9376388Z",
-            "score": 26.323200116475423,
-            "rbacGroupId": 9
-        }
-    ]
-}
- 
-
-```