다음을 통해 공유

요청 서비스 API 오류 코드

  • 아티클

Microsoft Entra Verified ID 자격 증명을 발급하고 확인할 수 있는 요청 서비스 REST API를 포함합니다. 이 문서에서는 요청 서비스 API에 대한 오류 코드를 지정합니다.

Error 개체

공개 미리 보기 중에 요청 서비스 API가 다음 형식으로 오류를 반환했습니다.

{
  "requestId": "4bb6726f77af7623ab52962323016442",
  "date": "Thu, 28 Apr 2022 14:30:54 GMT",
  "mscv": "17ppwf3uxR10MfRR.1",
  "error": {
    "code": "client_request.invalid_include_qr_code",
    "message": "The request contains `includeQRCode`, but it is not boolean."
  }
}

이제 이 형식이 다음과 같이 변경되어 더 간단한 오류 처리와 문제 해결에 대한 더 나은 지원을 모두 사용할 수 있습니다. 새 형식에서 외부 오류 코드 및 메시지 필드는 표준화된 값을 갖는 반면 innererror 개체는 오류의 원인에 대한 세부 정보를 제공합니다.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}
속성 Type 설명
requestId string 자동 생성된 요청 ID입니다.
date 날짜 오류가 발생한 시간입니다.
mscv string 내부 Microsoft 코드.
error 오류 외부 오류 개체

오류 유형

이제 error 개체가 API 호출에서 반환된 HTTP 상태 코드와 일치하여 개발자가 더 쉽게 오류를 처리할 수 있도록 합니다.

속성 Type 설명
code string HTTP 상태 코드와 일치하는 반환 오류 코드입니다.
message string 반환된 HTTP 상태 코드에도 종속된 표준화된 오류 메시지입니다.
innererror Innererror 오류의 원인에 대한 세부 정보를 제공합니다.

오류 코드 및 메시지

다음은 반환된 다른 HTTP 상태 코드에 매핑되는 가능한 최상위 code 값입니다.

HTTP 상태 코드 코드 message
400 badRequest 요청이 잘못되었습니다.
401 권한 없음 요청한 리소스에는 인증이 필요합니다.
403 사용할 수 없음 이 요청을 수행할 수 있는 권한이 없습니다.
404 notFound 요청된 리소스가 없습니다.
405 methodNotAllowed 요청된 메서드가 요청된 리소스에서 허용되지 않습니다.
406 notAcceptable 요청된 응답 형식은 지원되지 않습니다.
408 requestTimeout 요청 시간이 초과되었습니다.
409 충돌 서버 충돌로 인해 서버에서 요청을 수행할 수 없습니다.
410 없음 요청된 리소스를 더 이상 사용할 수 없습니다.
411 contentLengthRequired Content-length 헤더가 없습니다.
412 preconditionFailed 이 요청에 대한 전제 조건이 실패했습니다.
413 payloadTooLarge 페이로드가 너무 큽니다.
414 uriTooLong URI가 너무 깁니다.
415 unsupportedMediaType 지정한 미디어 형식이 지원되지 않습니다.
416 rangeNotSatisfiable 요청한 데이터 범위를 충족할 수 없습니다.
417 expectationFailed Expect 헤더를 충족할 수 없습니다.
421 misdirectedRequest 이 요청에 대한 응답을 생성할 수 없습니다.
422 unprocessableEntity 요청에 의미 체계 오류가 포함되어 있습니다.
423 잠김 원본 또는 대상 리소스가 잠겨 있습니다.
429 tooManyRequests 요청이 너무 많습니다. 나중에 다시 시도하세요.
431 requestHeaderFieldsTooLarge 요청 헤더 필드가 너무 큽니다.
500 internalServerError 서버에서 일반 오류가 발생했습니다.
501 notImplemented 서버는 요청된 함수를 지원하지 않습니다.
502 badGateway 다른 게이트웨이에서 잘못된 응답을 받았습니다.
503 serviceUnavailable 서버를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요.
504 gatewayTimeout 다른 게이트웨이에서 받은 시간 제한입니다.
507 insufficientStorage 요청에 대한 데이터를 저장할 수 없습니다.

내부 오류 유형

내부 오류 개체에는 현재 개발자가 오류를 조사하는 데 도움이 되는 유용한 오류 관련 세부 정보가 포함되어 있습니다.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}
속성 Type 설명
code string 내부 오류 코드. 오류 유형에 따라 표준화된 코드를 포함합니다.
message string 내부 오류 메시지. 오류에 대한 자세한 메시지를 포함합니다. 이 예제에서 includeQRCode 필드는 잘못된 형식입니다.
target string 선택 사항. 대상에는 이 오류를 일으키는 요청의 필드가 포함됩니다. 이 필드는 선택 사항이며 오류 유형에 따라 존재하지 않을 수 있습니다.

내부 오류 코드

코드 설명
badOrMissingField 요청에 대한 유효성 검사 문제가 발생할 때 반환됩니다. target 필드에는 문제를 일으키는 요청의 필드가 포함됩니다.
notFound 클라이언트가 요청하는 리소스를 찾을 수 없을 때 반환됩니다. target 필드에는 찾을 수 없는 리소스 이름/ID가 포함됩니다.
tokenError JWT 등과 같은 토큰에 대한 유효성 검사 문제에 대해 반환됩니다. target 필드에는 해당되는 경우 문제를 일으키는 토큰 이름이 포함됩니다.
transientError 클라이언트가 이후 단계에서 요청을 다시 시도하는 경우 성공적인 응답을 얻을 수 있는 모든 경우에 대해 반환됩니다. 이 코드가 반환되는 일반적인 예는 HTTP 429 코드가 다시 반환되는 경우입니다.

다음 단계