추천 API 응답 코드

적용 대상: 파트너 센터 | 파트너 센터 추천

적절한 역할: 조회 관리자 | 조회 사용자

파트너 센터 조회 REST API는 상태 코드가 포함된 JSON 개체를 반환합니다. 요청이 성공했는지 또는 실패한 이유를 나타내는 이 코드입니다.

성공 응답

2xx 상태 코드는 클라이언트의 요청이 성공적으로 수신, 이해 및 수락되었음을 나타냅니다. 다음 2xx 상태 코드는 성공 응답을 나타냅니다.

  • 200: 성공 확인
  • 201: 만든 리소스
  • 202: 수락됨
  • 204: 반환할 콘텐츠 없음

오류 응답

4xx 또는 5xx 상태 코드가 있는 응답에는 해당 코드의 오류 조건에 대한 세부 정보가 포함된 오류 메시지가 포함됩니다.

다음 표에서는 오류 시나리오에 대해 반환할 수 있는 HTTP 상태 코드를 나열하고 설명합니다.

상태 코드 상태 메시지 설명
400 잘못된 요청 형식이 잘못되었거나 올바르지 않으므로 요청을 처리할 수 없습니다.
401 비인가 필요한 인증 정보가 누락되었거나 리소스에 대해 유효하지 않습니다.
403 금지 요청한 리소스에 대한 액세스가 거부되었습니다. 사용자가 충분한 권한을 가지고 있지 않을 수 있습니다.
404 찾을 수 없음 요청된 리소스가 없습니다.
405 허용되지 않는 메서드 요청의 HTTP 메서드는 리소스에서 허용되지 않습니다.
406 수용할 수 없음 이 서비스는 Accept 헤더에 요청된 형식을 지원하지 않습니다.
409 충돌 현재 상태가 요청에 필요한 내용과 충돌합니다. 예를 들어, 지정된 상위 폴더가 존재하지 않을 수 있습니다.
410 없어진 서버에서 요청된 리소스를 더 이상 사용할 수 없습니다.
411 길이가 필요함 요청에 Content-Length 헤더가 필요합니다.
412 사전 조건 실패 요청에서 제공된 사전 조건(예: if-match 헤더)이 리소스의 현재 상태와 일치하지 않습니다.
413 요청된 엔터티가 너무 큽니다 요청 크기가 최대 한도를 초과합니다.
415 지원되지 않는 미디어 유형 요청의 콘텐츠 형식은 서비스가 지원하지 않는 형식입니다.
416 요청된 범위가 충족되지 않음 지정된 바이트 범위가 유효하지 않거나 사용할 수 없습니다.
422 처리할 수 없는 엔터티 의미상 올바르지 않으므로 요청을 처리할 수 없습니다.
423 잠김 액세스 중인 리소스가 잠겨 있습니다.
429 요청이 너무 많음 클라이언트 애플리케이션이 제한되며 잠시 동안 요청을 반복하려고 시도해서는 안 됩니다.
500 내부 서버 오류 요청을 처리하는 동안 내부 서버 오류가 발생했습니다.
501 구현되지 않음 요청한 기능이 구현되지 않았습니다.
503 서비스 이용 불가 유지 관리를 위해 서비스를 일시적으로 사용할 수 없거나 오버로드되었습니다. 지연 후 요청을 반복할 수 있으며 지연 길이는 Retry-After 헤더에 지정할 수 있습니다.
504 게이트웨이 시간 초과 서버는 프록시 역할을 하는 동안 요청을 완료하기 위해 액세스하는 데 필요한 업스트림 서버로부터 적시에 응답을 받지 못했습니다. 503과 함께 발생할 수 있습니다.
507 스토리지 부족 최대 스토리지 할당량에 도달했습니다.
509 대역폭 한도 초과 최대 대역폭 한도를 초과하기 위해 클라이언트 애플리케이션이 제한되었습니다. 앱은 일정 시간 후에 요청을 다시 시도할 수 있습니다.

오류 리소스 유형

오류 응답은 error라는 단일 속성을 포함하는 단일 JSON 개체입니다. 이 개체에는 오류에 대한 모든 세부 정보가 포함됩니다. 여기에 반환된 정보를 HTTP 상태 코드 대신 또는 HTTP 상태 코드와 함께 사용할 수 있습니다.

다음 표 및 코드 샘플에서는 오류 응답의 스키마를 설명합니다.

이름 형식 설명
코드 문자열 항상 반환됩니다. 발생한 오류의 종류를 나타냅니다. Null이 아닙니다.
메시지 string 항상 반환됩니다. 오류를 자세히 설명하고 더 많은 디버깅 정보를 제공합니다. null이 아니고 비어 있지 않음 최대 길이는 1,024자입니다.
내부 오류 개체 선택 사항. 오류에 대한 보다 구체적인 정보가 포함된 또 다른 오류 개체가 발생했습니다.
innerError.코드 숫자 문자열 innerError가 null이 아닌 경우 항상 반환됩니다. 최상위 오류 코드 값 아래에 보다 구체적인 오류 코드 정보를 제공합니다.
내부오류.메시지 스트링 innerError가 null이 아닌 경우 항상 반환됩니다. 최상위 오류 메시지 문자열 아래에 보다 구체적인 오류 메시지를 제공합니다.
innerError.details 배열 객체 선택 사항. 오류에 대한 자세한 내용을 포함합니다. 입력 유효성 검사 오류에 주로 유용합니다.
목표 string 선택 사항. 오류가 발생한 대상입니다.

샘플 오류 응답

{
  "error": {
    "code": "unauthenticated",
    "message": "The caller is not authenticated.",
    "innerError": {
      "code": "99902",
      "message": "Request not authenticated",
      "details": null
    }
  }
}

또 다른 예로 innerError.details 개체가 채워진 상태가 있습니다.

{
  "error": {
    "code": "invalidRequest",
    "message": "The request is malformed or incorrect.",
    "innerError": {
      "code": "99901",
      "message": "InvalidInput",
      "details": [
        {
          "InvalidReferralForCoSellConversion": [
            "If PartnerLed referral has no solution it cannot be converted to co-sell referral"
          ]
        }
      ]
    }
  }
}

코드 속성

code 속성에는 다음 가능한 값 중 하나가 포함됩니다. 이러한 오류를 처리할 수 있도록 앱을 준비해야 합니다.

코드 Http 상태 코드 설명
invalidRequest 400 요청이 잘못되었거나 형식이 잘못되었습니다.
unauthenticated 401 호출자가 인증되지 않습니다.
accessDenied 403 호출자에게 작업을 수행할 권한이 없습니다.
itemNotFound 404 리소스를 찾을 수 없습니다.
자원수정됨 409 호출자가 마지막으로 읽은 이후에 리소스가 변경되었으며, 이는 일반적으로 eTag 불일치 때문입니다.
전제조건실패 412 요청에서 제공된 사전 조건(예: if-match 헤더)이 리소스의 현재 상태와 일치하지 않습니다.
generalException 500 지정되지 않은 오류가 발생했습니다.
serviceNotAvailable 503 서비스를 사용할 수 없습니다. 지연 후 요청을 다시 시도하세요. Retry-After 헤더가 있을 수 있습니다.

메시지 속성

루트의 message 속성에는 개발자가 읽을 수 있는 오류 메시지가 포함되어 있습니다. 오류 메시지는 지역화되지 않으며 사용자에게 직접 표시해서는 안 됩니다. 코드는 message 값만 확인해서는 안 됩니다. 이러한 값은 언제든지 변경될 수 있으며, 실패한 요청과 관련된 동적 정보를 자주 포함하고 있기 때문입니다. code 속성에서 반환된 오류 코드에 대해 코딩하고, 자세한 내용은 메시지 텍스트와 결합해야 합니다.

InnerError 개체

개체에 innererror 보다 구체적인 오류 코드가 있는 더 많은 innererror 개체가 재귀적으로 포함될 수 있습니다. 클라이언트 애플리케이션은 오류를 처리할 때 사용 가능한 모든 오류 코드를 반복하고 이해한 가장 자세한 코드를 사용해야 합니다.

앱이 중첩된 innererror 개체 내에서 발생할 수 있는 몇 가지 오류가 더 있습니다. 앱은 이러한 오류를 처리할 필요가 없지만 선택하는 경우 수행할 수 있습니다. 서비스는 새 오류 코드를 추가하거나 언제든지 이전 오류 코드를 반환하지 않을 수 있으므로 모든 앱이 [기본 오류 코드]를 처리할 수 있어야 합니다.

오류 코드

API에서 반환하는 오류 코드는 다음과 같습니다.

HTTP 상태 HTTP 오류 코드 오류 코드 설명
잘못된 요청 400 99901 잘못된 입력
승인되지 않음 401 99902 무단 액세스
잘못된 요청 400 99903 입력 누락
찾을 수 없음 404 99,904 리소스를 찾을 수 없음
내부 서버 오류 500 99905 오류가 지정되지 않음
요청이 너무 많습니다 429 99906 요청이 너무 많습니다.
내부 서버 오류 500 99907 일시적인 내부 오류
잘못된 요청 400 99908 속성을 업데이트할 수 없음
잘못된 요청 400 99909 속성이 null이 될 수 없습니다.
전제 조건 실패 412 99910 Etag 값이 일치하지 않음
잘못된 요청 400 99911 초대에 사용할 추천 상태가 유효하지 않습니다.
잘못된 요청 400 99912 'name' 형식의 솔루션이 필요합니다.
금지 403 99913 조직이 리소스를 생성하는 허용 목록에 포함되지 않음
금지 403 99914 공동 판매 계약에 참여할 수 있는 허용 목록에 없는 조직
내부 서버 오류 500 99915 내부 요청 실행 실패
충돌 409 99917 다른 요청을 통해 이미 수정된 리소스
선행 조건 실패 412 99918 요청에서 제공된 사전 조건(예: if-match 헤더)이 리소스의 현재 상태와 일치하지 않습니다.
잘못된 요청 400 99919 업데이트할 추천 자격이 유효하지 않습니다.
서버 내부 오류 500 99999 요청을 처리하는 동안 일반적인 예외
  • Last updated on