Handling REST API errors
HTTP error responses are divided into two categories:
- Client error (400-code level) – the client sent an invalid request or the request isn't in accordance with definitions.
- Server error (500-level) – the server temporarily failed to fulfill the request or a server error occurred. Try sending the HTTP request again.
The error codes listed in the following table may be returned by an operation on any of Microsoft Defender for Endpoint APIs.
- In addition to the error code, every error response contains an error message, which can help resolve the problem.
- The message is a free text that can be changed.
- At the bottom of the page, you can find response examples.
Applies to:
Want to experience Defender for Endpoint? Sign up for a free trial.
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} isn't supported for this action. |
ClientVersionNotSupported | BadRequest (400) | {The requested action} is supported on client version {supported client version} and above. |
Unauthorized | Unauthorized (401) | Unauthorized (invalid or expired authorization header). |
Forbidden | Forbidden (403) | Forbidden (valid token but insufficient permission for the action). |
DisabledFeature | Forbidden (403) | Tenant feature isn't 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} wasn't found. |
TooManyRequests | Too Many Requests (429) | Response represents reaching quota limit either by number of requests or by CPU. |
InternalServerError | Internal Server Error (500) | (No error message, retry the operation.) |
The HTTP client may receive a 'Too Many Requests error (429)' when the number of HTTP requests in a given time frame exceeds the allowed number of calls per API.
The HTTP client should delay resubmitting further HTTPS requests and then submit them in a way that complies with the rate limitations. A Retry-After in the response header indicating how long to wait (in seconds) before making a new request
Ignoring the 429 response or trying to resubmit HTTP requests in a shorter time frame gives a return of the 429 error code.
The submitted body parameters are currently case-sensitive.
If you experience an InvalidRequestBody or MissingRequiredParameter errors, it might be caused from a wrong parameter capital or lower-case letter.
Review the API documentation page and check that the submitted parameters match the relevant example.
Each error response contains a unique ID parameter for tracking.
The property name of this parameter is "target".
When contacting us about an error, attaching this ID helps find the root cause of the problem.
{
"error": {
"code": "ResourceNotFound",
"message": "Machine 123123123 was not found",
"target": "43f4cb08-8fac-4b65-9db1-745c2ae65f3a"
}
}
{
"error": {
"code": "InvalidRequestBody",
"message": "Request body is incorrect",
"target": "1fa66c0f-18bd-4133-b378-36d76f3a2ba0"
}
}
Tip
Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.