다음을 통해 공유


요청 서비스 API 오류 코드

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

오류 개체

공개 미리 보기 중에 Request Service 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"
    }
  }
}
재산 묘사
requestId 문자열 자동 생성된 요청 ID입니다.
date 날짜 오류의 시간입니다.
mscv 문자열 내부 Microsoft 코드입니다.
error 오류 외부 오류 개체

오류 유형

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

재산 묘사
code 문자열 HTTP 상태 코드와 일치하는 반환 오류 코드입니다.
message 문자열 반환된 HTTP 상태 코드에도 종속된 표준화된 오류 메시지입니다.
innererror Innererror 오류의 원인에 대한 세부 정보를 제공합니다.

오류 코드 및 메시지

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

HTTP 상태 코드 코드 메시지
400 badRequest 요청이 잘못되었습니다.
401 무단 요청된 리소스에는 인증이 필요합니다.
403 금지된 이 요청을 수행할 수 있는 권한이 없습니다.
404 notFound 요청된 리소스가 없습니다.
405 methodNotAllowed 요청된 메서드는 요청된 리소스에서 허용되지 않습니다.
406 허용되지 않음 요청된 응답 형식은 지원되지 않습니다.
408 requestTimeout 요청 시간이 초과되었습니다.
409 충돌 서버 충돌로 인해 서버가 요청을 처리할 수 없습니다.
410 지나간 요청된 리소스를 더 이상 사용할 수 없습니다.
411 contentLengthRequired Content-Length 헤더가 없습니다.
412 preconditionFailed 이 요청에 대한 사전 조건이 실패했습니다.
413 payloadTooLarge 페이로드가 너무 큽합니다.
414 uriTooLong URI가 너무 깁니다.
415 unsupportedMediaType 지정된 미디어 형식이 지원되지 않습니다.
416 rangeNotSatisfiable 요청된 데이터 범위를 충족할 수 없습니다.
417 expectationFailed 예상 헤더를 충족할 수 없습니다.
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"
    }
  }
}
재산 묘사
code 문자열 내부 오류 코드입니다. 오류 유형에 따라 표준화된 코드를 포함합니다.
message 문자열 내부 오류 메시지입니다. 오류에 대한 자세한 메시지를 포함합니다. 이 예제에서 includeQRCode 필드는 잘못된 형식입니다.
target 문자열 선택적. 대상에는 이 오류를 일으키는 요청의 필드가 포함됩니다. 이 필드는 선택 사항이며 오류 유형에 따라 존재하지 않을 수 있습니다.

내부 오류 코드

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

다음 단계