REST API 오류 처리
HTTP 오류 응답은 다음 두 가지 범주로 나뉩니다.
- 클라이언트 오류(400 코드 수준) – 클라이언트가 잘못된 요청을 보냈거나 요청이 정의에 맞지 않습니다.
- 서버 오류(500 수준) - 서버가 일시적으로 요청을 이행하지 못했거나 서버 오류가 발생했습니다. HTTP 요청을 다시 보내 보세요.
다음 표에 나열된 오류 코드는 엔드포인트용 Microsoft Defender API에 대한 작업에서 반환될 수 있습니다.
- 오류 코드 외에도 모든 오류 응답에는 문제를 resolve 데 도움이 될 수 있는 오류 메시지가 포함됩니다.
- 메시지는 변경할 수 있는 무료 텍스트입니다.
- 페이지 아래쪽에서 응답 예제를 찾을 수 있습니다.
적용 대상:
엔드포인트용 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.
피드백
https://aka.ms/ContentUserFeedback
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요.다음에 대한 사용자 의견 제출 및 보기