REST API 오류 처리

  • 아티클

HTTP 오류 응답은 다음 두 가지 범주로 나뉩니다.

  • 클라이언트 오류(400 코드 수준) – 클라이언트가 잘못된 요청을 보냈거나 요청이 정의에 맞지 않습니다.
  • 서버 오류(500 수준) - 서버가 일시적으로 요청을 이행하지 못했거나 서버 오류가 발생했습니다. HTTP 요청을 다시 보내 보세요.

다음 표에 나열된 오류 코드는 엔드포인트용 Microsoft Defender API에 대한 작업에서 반환될 수 있습니다.

  • 오류 코드 외에도 모든 오류 응답에는 문제를 resolve 데 도움이 될 수 있는 오류 메시지가 포함됩니다.
  • 메시지는 변경할 수 있는 무료 텍스트입니다.
  • 페이지 아래쪽에서 응답 예제를 찾을 수 있습니다.

적용 대상:

  • .. /microsoft-defender-endpoint.md
  • .. /microsoft-defender-endpoint.md

엔드포인트용 Defender를 경험하고 싶으신가요? 무료 평가판을 신청하세요.

오류 코드 HTTP 상태 코드 메시지
BadRequest BadRequest (400) 일반 잘못된 요청 오류 메시지입니다.
ODataError BadRequest (400) 잘못된 OData URI 쿼리(특정 오류가 지정됨).
InvalidInput BadRequest (400) 잘못된 입력 {잘못된 입력}.
InvalidRequestBody BadRequest (400) 잘못된 요청 본문입니다.
InvalidHashValue BadRequest (400) 해시 값 {잘못된 해시}이(가) 잘못되었습니다.
InvalidDomainName BadRequest (400) 도메인 이름 {잘못된 도메인}이(가) 잘못되었습니다.
InvalidIpAddress BadRequest (400) IP 주소 {잘못된 IP}이(가) 잘못되었습니다.
InvalidUrl BadRequest (400) URL {잘못된 URL}이(가) 잘못되었습니다.
MaximumBatchSizeExceeded BadRequest (400) 최대 일괄 처리 크기를 초과했습니다. 수신됨: {batch size received}, 허용됨: {batch size allowed}.
MissingRequiredParameter BadRequest (400) 매개 변수 {누락된 매개 변수}가 없습니다.
OsPlatformNotSupported BadRequest (400) OS 플랫폼 {클라이언트 OS 플랫폼}은(는) 이 작업에 대해 지원되지 않습니다.
ClientVersionNotSupported BadRequest (400) {요청된 작업}은(는) 클라이언트 버전 {지원되는 클라이언트 버전} 이상에서 지원됩니다.
무단 권한 없음(401) 권한 없음(유효하지 않거나 만료된 권한 부여 헤더)입니다.
사용 권한 없음 사용할 수 없음(403) 사용할 수 없음(유효한 토큰이지만 작업에 대한 권한이 부족).
DisabledFeature 사용할 수 없음(403) 테넌트 기능을 사용할 수 없습니다.
DisallowedOperation 사용할 수 없음(403) {허용되지 않는 작업 및 이유}.
NotFound 찾을 수 없음(404) 일반 찾을 수 없음 오류 메시지입니다.
ResourceNotFound 찾을 수 없음(404) 리소스 {요청된 리소스}를 찾을 수 없습니다.
TooManyRequests 요청이 너무 많음(429) 응답은 요청 수 또는 CPU별로 할당량 제한에 도달한 것을 나타냅니다.
InternalServerError 내부 서버 오류(500) (오류 메시지가 없으면 작업을 다시 시도하세요.)

제한

지정된 시간 프레임의 HTTP 요청 수가 API당 허용되는 호출 수를 초과하는 경우 HTTP 클라이언트는 '너무 많은 요청 오류(429)'를 받을 수 있습니다.

HTTP 클라이언트는 추가 HTTPS 요청 다시 제출을 지연한 다음 속도 제한을 준수하는 방식으로 제출해야 합니다. 새 요청을 만들기 전에 대기할 시간(초)을 나타내는 응답 헤더의 Retry-After

429 응답을 무시하거나 짧은 시간 프레임에서 HTTP 요청을 다시 제출하려고 하면 429 오류 코드가 반환됩니다.

본문 매개 변수는 대/소문자를 구분합니다.

제출된 본문 매개 변수는 현재 대/소문자를 구분합니다.

InvalidRequestBody 또는 MissingRequiredParameter 오류가 발생하는 경우 잘못된 매개 변수 대/소문자 또는 소문자로 인해 발생할 수 있습니다.

API 설명서 페이지를 검토하고 제출된 매개 변수가 관련 예제와 일치하는지 검사.

상관 관계 요청 ID

각 오류 응답에는 추적을 위한 고유 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 Defender Tech Community의 Microsoft 보안 커뮤니티와 Engage.