處理 REST API 錯誤

HTTP 錯誤回應分為兩類：

• 用戶端錯誤 (400 程式碼層級) – 用戶端傳送了無效的要求，或要求不符合定義。
• 伺服器錯誤 (500 級) – 伺服器暫時無法滿足請求或發生伺服器錯誤。 請再次嘗試傳送 HTTP 要求。

下表中列出的錯誤碼可能會由任何適用於端點的 適用於端點的 Microsoft Defender API 上的作業傳回。

• 除了錯誤代碼之外，每個錯誤回應都包含錯誤訊息，這有助於解決問題。
• 該消息是可以更改的自由文本。
• 在頁面底部，您可以找到回應範例。

錯誤碼	HTTP 狀態碼	郵件
錯誤請求	BadRequest (400)	一般錯誤要求錯誤訊息。
OData錯誤	BadRequest (400)	OData URI 查詢無效 (指定特定錯誤) 。
無效輸入	BadRequest (400)	輸入無效 {輸入無效}。
無效要求內文	BadRequest (400)	請求內文無效。
無效雜湊值	BadRequest (400)	雜湊值 {無效雜湊} 無效。
無效網域名稱	BadRequest (400)	網域名稱 {無效網域} 無效。
無效的 IpAddress	BadRequest (400)	IP 位址 {無效的 IP} 無效。
無效網址	BadRequest (400)	URL {無效的URL}無效。
MaximumBatchSize已超出	BadRequest (400)	已超出批次大小上限。 已接收：{已收到批次大小}，允許：{允許的批次大小}。
MissingRequired參數	BadRequest (400)	參數 {遺漏的參數} 遺失。
OsPlatform不支援	BadRequest (400)	此動作不支援 OS 平台 {用戶端 OS 平台}。
用戶端版本不支援	BadRequest (400)	{請求的動作} 在用戶端版本 {supported client version} 及更高版本上受支援。
未經授權	未經授權 (401)	未授權 (無效或過期的授權標頭) 。
禁止	禁 (403)	禁止 (有效的權杖，但動作) 的權限不足。
已停用功能	禁 (403)	未啟用租用戶功能。
不允許操作	禁 (403)	{不允許的操作和原因}。
找不到	未找到 (404)	General Not Found 錯誤訊息。
ResourceNot找到	未找到 (404)	找不到資源 {要求的資源}。
TooMany請求	請求太多 (429)	回應代表依要求數目或 CPU 達到配額限制。
InternalServer錯誤	內部伺服器錯誤 (500)	(沒有錯誤訊息，請重試操作 )

節流

當指定時間範圍內的 HTTP 請求數量超過每個 API 允許的呼叫數時，HTTP 用戶端可能會收到「請求過多錯誤 (429) 」。

HTTP 用戶端應延遲重新提交進一步的 HTTPS 要求，然後以符合速率限制的方式提交。 回應標頭中的 Retry-After，指出在提出新請求之前等待 (多長時間（以秒) 為單位）

忽略 429 回應或嘗試在較短的時間範圍內重新提交 HTTP 要求會傳回 429 錯誤碼。

正文參數區分大小寫

提交的內文參數目前區分大小寫。

如果您遇到 InvalidRequestBody 或 MissingRequiredParameter 錯誤，可能是因為參數大寫或小寫字母錯誤所造成。

檢閱 API 文件頁面，並檢查提交的參數是否與相關範例相符。

相互關聯要求識別碼

每個錯誤回應都包含用於追蹤的唯一 ID 參數。

此參數的屬性名稱為「target」。

就錯誤聯絡我們時，附加此 ID 有助於找出問題的根本原因。

範例

{
    "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"
    }
}

提示

想要深入了解? 在我們的技術社區中與Microsoft安全社區Engage：適用於端點的 Microsoft Defender技術社區。