Table of contents

오류 코드 및 오류 처리 | Graph API concepts(Graph API 개념)

Jimaco Brannian|마지막 업데이트: 2017-02-23
|
1 기고자

적용 대상: Graph API | Azure AD(Active Directory)

Azure AD(Active Directory) Graph API를 사용하는 클라이언트 응용 프로그램은 다양한 조건에 가능한 매끄럽게 대응하고 고객에게 최상의 환경을 제공하는 방식으로 오류 처리 논리를 구현해야 합니다. 이 항목에서는 Azure AD Graph API에서 반환하고 처리 방법에 대한 일반 지침을 제공하는 오류 유형을 설명합니다.

중요

Azure AD Graph API 기능은 단일 액세스 토큰으로 단일 끝점을 통해 모두 액세스되는 Outlook, OneDrive, OneNote, Planner 및 Office Graph와 같은 다른 Microsoft 서비스의 API도 포함하는 통합 API인 Microsoft Graph를 통해서도 사용할 수 있습니다.

Graph API 오류 처리

오류 유형

Graph API 오류는 다음 범주에서 발생합니다.

  • 클라이언트 오류. 클라이언트 오류는 400 시리즈 HTTP 상태 코드로 표시됩니다. 잘못된 값을 가진 개체, 필수 속성 또는 속성 값이 누락된 개체, 존재하지 않는 리소스 액세스 시도, 읽기 전용 속성 업데이트 시도, 필수 인증 토큰 생략 등이 포함됩니다. 이러한 오류를 해결하려면 요청을 재시도하기 전에 기본 문제를 해결하십시오.
  • 서버 오류. 서버 오류는 일시적인 디렉터리 실패 등 500 시리즈 HTTP 상태 코드로 표시됩니다. 이러한 오류는 대부분 일시적이며 요청을 재시도하면 해결할 수 있습니다.
  • 네트워크/프로토콜 오류. 요청을 보내거나 응답을 받는 동안 호스트 이름 확인 오류, 중간에 닫힌 연결, SSL 협상 오류 등의 다양한 네트워크 관련 오류가 발생할 수 있습니다. 이러한 오류는 대부분 재시도하여 해결할 수 없습니다. 기본 문제를 해결해야 합니다. 그러나 호스트 이름 확인 실패, 시간 초과 등의 일부 오류는 요청을 재시도하여 해결할 수 있습니다.

오류 메시지 구조

Graph API 오류에는 HTTP 상태 코드, 메시지 및 값으로 구성된 특정 형식의 본문이 있습니다. 오류 처리 논리에서 오류 본문의 속성을 사용합니다.

참고: 일부 HTTP 응답에는 요청이 프록시 및 게이트웨이 서비스를 통해 라우팅되어 코드/메시지/값 응답 본문이 포함되어 있지 않을 수도 있습니다. HTTP 상태 코드만 기준으로 오류를 처리할 수 있는 기본 논리를 포함해야 합니다.

다음은 HTTP 400 Request_BadRequest 오류의 예입니다.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …

 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

각 메시지 본문에는 코드, 메시지 및 값 속성이 있습니다.

  • 코드: 코드를 기준으로 분기되도록 오류 처리 논리를 디자인합니다.

      "code" : "Request_BadRequest"
    
  • 메시지: 사람이 읽을 수 있는 오류 메시지를 나타내는 언어/값 튜플입니다. 콘텐츠는 값 필드에 있습니다. 다음 예에서는 mailNickname 속성 값이 누락되어 요청이 실패합니다.

      "message" : {
           "lang" : "en",
           "value" : "A value is required for property 'mailNickname' of resource 'Group'."
      }
    
  • : 실패 특성에 대한 자세한 정보를 제공하는 이름/값 쌍의 컬렉션입니다. 다음 예에서는 값이 포함되어 있지 않습니다.

      "values" : null
    

오류 코드 참조

HTTP 오류 코드

다음 표에서는 Graph API 오류 코드, 오류 메시지 및 오류 수정 시 고려할 작업을 보여 줍니다.

가급적 긴 시간 간격 동안 분포("백오프 간격으로 다시 시도")되면서 무작위 분포 요소가 포함된 다시 시도에 응답하는 오류는 일반적으로 HTTP 500 시리즈 오류입니다. 400 시리즈 오류는 다시 시도하기 전에 수정해야 할 문제를 나타냅니다.

HTTP 상태 코드오류 코드오류 메시지세부 정보
400Directory_ExpiredPageToken지정된 페이지의 토큰 값이 만료되었으며 더 이상 요청에 포함할 수 없습니다.
400Directory_ResultSizeLimitExceeded결과 크기 한도를 초과했습니다.요청이 너무 많은 결과와 연결되어 있어서 수행할 수 없습니다. 이 오류는 자주 발생하지 않습니다.
400DomainVerificationCodeNotFound확인 프로세스에서 일치하는 확인 코드가 있는 TXT 레코드를 찾을 수 없으므로 도메인을 확인할 수 없습니다.
400ObjectConflict이 회사의 확인되지 않은 도메인에 도메인 이름이 이미 있습니다.
400ObjectConflict이 회사의 확인된 도메인에 도메인 이름이 이미 있습니다.
400ObjectInUse현재 사용자, 그룹 또는 다중 테넌트 응용 프로그램에서 참조하는 도메인을 삭제할 수 없습니다.
400ObjectPendingDeletion삭제 보류 중인 기존 도메인을 확인할 수 없습니다.
400ObjectPendingTakeover테넌트 인수 중 도메인을 삭제할 수 없습니다.
400Request_BadRequest잘못된 요청입니다. 다시 시도하기 전에 요청을 수정하십시오.잘못된 속성 값 또는 지원되지 않는 쿼리 인수와 같은 요청 오류를 나타냅니다. 다시 시도하기 전에 요청을 수정하십시오.
400Request_DataContractVersionMissing데이터 계약 버전 매개 변수가 없습니다. 사용자의 모든 요청을 쿼리 매개 변수로 api 버전을 포함합니다.
400Request_InvalidDataContractVersion지정한 api 버전이 올바르지 않습니다. 값은 지원 되는 버전과 정확히 일치해야 합니다.
400Request_InvalidRequestUrl요청 url이 올바르지 않습니다. 요청은 /tenantdomainname/Entity 또는 /$metadata와 유사해야 합니다. 테넌트 도메인 이름은 확인되거나, 확인되지 않은 도메인 이름이거나 컨텍스트 id 중 하나일 수 있습니다.
400Request_UnsupportedQueryGET 요청은 지원되지 않습니다. 요청 매개 변수를 수정하고 다시 시도하십시오.
401Authentication_ExpiredToken액세스 토큰이 만료되었습니다. 요청을 제출하기 전에 갱신하십시오.액세스 토큰이 만료되었습니다. 토큰을 갱신하고 다시 제출하십시오.
401Authentication_MissingOrMalformed액세스 토큰이 없거나 형식이 잘못되었습니다.인증 헤더의 access_token 값이 없거나 형식이 잘못되었습니다. 이 값은 필수입니다. 인증 토큰의 값을 사용하십시오.
401Authorization_IdentityDisabled호출 응용 프로그램 보안 주체를 사용할 수 없습니다.액세스 토큰에서 지정된 보안 주체가 디렉터리에 있지만 사용할 수 없습니다. 디렉터리에서 계정을 다시 사용하도록 설정하고 다시 시도하십시오.
401Authorization_IdentityNotFound호출 응용 프로그램의 ID를 설정할 수 없습니다.액세스 토큰에 지정된 보안 주체를 디렉터리에서 찾을 수 없습니다. 이러한 오류는 토큰이 유효하지 않고 디렉터리에서 보안 주체가 삭제되었거나 디렉터리 동기화가 지연되기 때문에 발생할 수 있습니다.
403Authentication_Unauthorized권한이 없는 요청입니다.토큰에 잘못되거나 지원되지 않는 클레임이 있습니다. 요청 토큰을 다시 가져오고 요청을 다시 시도하십시오.
403Authorization_RequestDenied지정된 자격 증명에 이 요청을 수행할 수 있는 권한이 없습니다.권한이 없어서 요청이 거부됩니다. 예를 들어 관리 권한이 없는 보안 주체는 리소스를 삭제할 권한이 없습니다.
403Directory_QuotaExceeded{tenantName}에 대한 디렉터리 개체 할당량 한도를 초과했습니다. 관리자에게 할당량 한도를 늘리거나 개체를 삭제하여 사용된 할당량을 줄이도록 요청하십시오.디렉터리 할당량이 초과되었습니다. 테넌트에 너무 많은 개체가 있거나 개체에 너무 많은 값이 있는 것 같습니다. 주체에 대해 너무 많은 개체가 생성된 경우에도 이 문제가 발생합니다. 테넌트 또는 보안 주체에 대한 최대 허용 개체 수를 늘리거나 만들기/업데이트 요청에 포함된 값 수를 줄이십시오.
404Directory_ObjectNotFound디렉터리에서 회사 정보를 읽을 수 없습니다.
404Request_ResourceNotFound{resource} 리소스가 존재하지 않거나 쿼리된 참조 속성 개체 중 하나가 존재하지 않습니다.URI에서 식별하는 리소스가 없습니다. 값을 수정하고 요청을 다시 시도하십시오.
409Request_MultipleObjectsWithSameKeyValue결과에 단일 리소스가 필요하지만 여러 리소스가 발견되었습니다. 충돌을 해결하려면 개체를 업데이트하세요.이 오류는 동일한 키 값을 가진 개체가 두 개 이상 있는 경우, 예를 들어 두 명의 사용자가 동일한 UserPrincipalName을 가지고 있는 경우 발생합니다.
429요청이 너무 많음.이 오류는 요청이 제한될 때 발생합니다. 응답 헤더의 Retry-After 값에서 제안 대기 시간이 반환됩니다. 권장 시간(초) 동안 기다린 후 요청을 다시 시도하세요.
500Service_InternalServerError내부 서버 오류가 발생했습니다.요청을 처리하는 동안 내부 서버 오류가 발생했습니다.
502[모두]“... 서비스를 사용할 수 없습니다."게이트웨이 또는 프록시로 사용되는 서버에서 요청을 처리하는 동안 다른 서버에서 오류가 발생했습니다. 잠시 기다린 다음 요청을 다시 시도하십시오.
503Directory_ConcurrencyViolation테넌트에 대한 동시 요청으로 인해 오류가 발생했습니다. 잠시 기다린 후 다시 시도하세요.
503DNS 확인 중 오류가 발생했습니다(참고: 현재 DNS 중단처럼 여러 가지 이유로 인해 오류가 발생할 수 있습니다).
Authentication_Unknown내부 서버 오류입니다.다른 오류 코드가 적용되지 않을 때 이 오류 코드가 사용됩니다.
Authentication_UnsupportedTokenType제공된 토큰 유형이 처리되지 않습니다. 전달자 토큰만 지원됩니다.토큰 유형이 지원되지 않습니다. 다시 요청을 시도하기 전에 토큰 유형을 수정하십시오.
Directory_BindingRedirection로컬로 사용할 수 있는 테넌트 정보가 없습니다. 다음 URL을 사용하여 정보를 가져오십시오.데이터 센터에서 테넌트 파티션을 사용할 수 없는 경우 클라이언트는 응답에서 반환된 URl에 연결해야 합니다.
Directory_BindingRedirectionInternalServerError로컬로 사용할 수 있는 테넌트 정보가 없습니다. 서버에서 가장 가까운 데이터 센터 끝점을 채우는 동안 내부 오류가 발생했습니다.바인딩 리디렉션 예외가 발생하면 서비스에 대한 가장 가까운 데이터 센터 끝점 목록이 채워집니다. 이 오류는 목록을 채울 때 예외를 나타냅니다. 다시 쿼리를 시도하십시오.
Directory_CompanyNotFound디렉터리에서 회사 정보를 읽을 수 없습니다.디렉터리 서비스에서 회사 정보를 로드하는 동안 오류가 발생했습니다.
Directory_ReplicaUnavailable기본 설정 복제본을 사용할 수 없습니다. 복제본 세션 키 헤더 없이 다시 시도하십시오.x-ms-replica-session-key 헤더를 생략하고 다시 시도하십시오.
Headers_DataContractVersionMissing데이터 계약 버전 헤더가 없습니다. 요청에 x-ms-dirapi-data-contract-version을 포함하십시오.요청에 클라이언트 계약 버전이 없습니다.
Headers_HeaderNotSupported{0} 헤더는 현재 지원되지 않습니다.요청에 지원되지 않는 HTTP 헤더가 있습니다. 헤더를 변경하고 다시 요청을 시도하십시오.
Request_InvalidReplicaSessionKey제공된 복제본 세션 키가 잘못되었습니다.복제본 세션 키를 수정하고 다시 요청을 시도하십시오.
Request_ThrottledPermanently요청이 영구적으로 제한되었습니다. 지원 서비스에 문의하여 문제를 해결하십시오.테넌트가 반복적이며 영구적으로 토큰 요청 속도 한도를 초과했습니다. 서비스가 다시 협상될 때까지 테넌트의 요청이 거부됩니다. 도움이 필요하면 Microsoft 지원 팀에 문의하십시오.

추가 리소스

© 2017 Microsoft