소개
이 문서는 Microsoft Fabric REST API에서 반환하는 일반적인 오류를 이해하고 해결하는 데 도움이 됩니다. 서비스에서 사용하는 표준 오류 형식을 설명하고 가장 자주 발생하는 HTTP 상태 코드를 해결하기 위한 지침을 제공합니다.
Microsoft Fabric 오류 응답 이해
Microsoft Fabric REST API에 대한 요청을 처리하는 동안 오류가 발생하면 서비스는 응답 본문에 표준 ErrorResponse 개체를 반환합니다.
문제를 해결할 때는 항상 requestId을 캡처하고 기록하십시오. 이는 요청을 고유하게 식별하며 Microsoft 지원에 문의할 때 필요합니다. 요청 ID는 응답 본문과 응답 헤더 모두에서 사용할 수 있습니다.
중요
errorCode값은 안정적이고 계약 기반입니다.- 사람이 읽을 수 있는
message텍스트는 시간이 지남에 따라 변경될 수 있으며 프로그래밍 방식으로 구문 분석해서는 안 됩니다.
오류 응답 스키마
| 이름 | 유형 | Description |
|---|---|---|
errorCode |
string |
오류 조건에 대한 안정적인 식별자입니다. 오류 처리 논리를 구현할 때 이 값을 사용합니다. |
message |
string |
사람이 읽을 수 있는 오류 설명입니다. |
moreDetails |
ErrorResponseDetails[] |
추가 오류 세부 정보의 선택적 목록입니다. |
relatedResource |
ErrorRelatedResource |
해당하는 경우 오류와 관련된 리소스에 대한 정보입니다. |
requestId |
string |
실패한 요청의 고유 식별자입니다. Microsoft 지원에 문의할 때 이 값을 포함합니다. |
ErrorResponseDetails 스키마
복잡한 오류 시나리오에 대한 추가 컨텍스트를 제공합니다.
| 이름 | 유형 | Description |
|---|---|---|
errorCode |
string |
특정 오류 세부 정보를 설명하는 안정적인 식별자입니다. |
message |
string |
오류 세부 사항에 대한 사람이 읽을 수 있는 설명입니다. |
relatedResource |
ErrorRelatedResource |
이 특정 오류 세부 정보와 연결된 리소스입니다. |
ErrorRelatedResource 스키마
오류와 관련된 리소스를 식별합니다.
| 이름 | 유형 | Description |
|---|---|---|
resourceId |
string |
오류와 관련된 리소스의 ID입니다. |
resourceType |
string |
리소스의 형식(예: 작업 영역, 항목 또는 용량)입니다. |
일반적인 HTTP 오류 시나리오
다음 섹션에서는 일반적인 근본 원인 및 권장 해결 방법과 함께 Microsoft Fabric REST API에서 반환되는 일반적인 HTTP 상태 코드에 대해 설명합니다.
API는 401 – 권한 없음을 반환합니다.
401 응답은 인증 또는 액세스 토큰 유효성 검사 중에 요청이 실패했음을 나타냅니다.
일반적인 근본 원인
| 오류 코드 | Description | 해결 방법 |
|---|---|---|
TokenExpired |
액세스 토큰이 만료되었습니다. | 새 액세스 토큰을 획득하고 요청을 다시 시도합니다. |
InsufficientScopes |
액세스 토큰에는 필요한 범위가 포함되지 않습니다. | API 사양에 설명된 대로 필요한 범위를 요청하도록 애플리케이션을 업데이트하거나 Microsoft Entra 애플리케이션 등록을 업데이트합니다. |
API는 403 – 사용할 수 없음을 반환합니다.
403 응답은 호출자가 인증되었지만 대상 리소스에 대해 요청된 작업을 수행할 수 있는 충분한 권한이 없음을 나타냅니다.
일반적인 근본 원인
| 오류 코드 | Description | 해결 방법 |
|---|---|---|
InsufficientPrivileges |
호출자에게 리소스에 액세스하는 데 필요한 권한이 없습니다. | 작업 영역 또는 리소스 관리자에게 호출하는 사용자 또는 서비스 주체에게 충분한 권한을 부여하도록 요청합니다. |
API는 404 – 찾을 수 없음을 반환합니다.
404 응답은 요청되거나 참조된 리소스가 없거나 호출자가 액세스할 수 없음을 나타냅니다.
참고
개별 API는 추가 API 관련 오류 코드를 정의할 수 있습니다. 신뢰할 수 있는 세부 정보는 항상 API 사양을 참조하세요.
일반적인 근본 원인
| 오류 코드 | Description | 해결 방법 |
|---|---|---|
WorkspaceNotFound |
지정된 작업 영역을 찾을 수 없습니다. | 올바른 작업 영역 개체 ID가 제공되었는지 확인합니다. |
EntityNotFound |
요청된 리소스를 찾을 수 없습니다. | 올바른 리소스 ID가 제공되었는지 확인합니다. 누락된 relatedResource 엔터티는 오류 응답 필드에서 식별됩니다. |
API는 429 – 너무 많은 요청을 반환합니다.
429 응답은 요청이 제한되었음을 나타냅니다. Microsoft Fabric 각각 응답 본문에서 다른 errorCode 것으로 식별되는 두 가지 이유로 429 상태 코드를 반환합니다.
일반적인 근본 원인
| 오류 코드 | Description | 해결 방법 |
|---|---|---|
RequestBlocked |
요청 속도가 서비스의 제한 한도를 초과했습니다. | 다시 시도하기 전에 헤더에 Retry-After 지정된 기간을 기다립니다.
애플리케이션의 핸들 속도 제한을 참조하세요. |
CapacityLimitExceeded |
귀하의 용량에서 소비된 컴퓨팅 용량(용량 단위)이 구매한 Fabric SKU 한도를 초과했습니다. | 나중에 요청을 다시 시도합니다. 용량 제한 처리를 참조하세요. |
속도 제한(RequestBlocked)
오류는 RequestBlocked 요청 속도가 서비스의 제한 제한을 초과했음을 나타냅니다.
- 제한은 호출자 ID별로 적용됩니다.
- 속도 제한은 일반적으로 1분 기간 동안 평가됩니다.
타이밍 정보 다시 시도
속도 제한이 발생하면 다음 두 위치에서 재시도 정보가 제공됩니다.
응답 본문(
message)
예제:
"Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"Retry-AfterHTTP 응답 헤더
다시 시도하기 전에 클라이언트가 대기해야 하는 시간(초)을 지정합니다.
재시도 논리를 Retry-After 구현할 때 항상 헤더를 선호합니다.
애플리케이션에서 속도 제한 처리
애플리케이션은 다음을 수행해야 합니다.
- HTTP 429 응답을 검색합니다.
-
Retry-After헤더를 구문 분석하고 준수합니다. - 대규모 시나리오에서는 지터가 포함된 지수 백오프와 같은 제한된 재시도 정책을 적용하세요.
- 무한 재시도 루프를 방지합니다.
속도 제한 가능성 줄이기
- 사용 가능한 경우 대량 및 일괄 처리 작업을 사용합니다.
- 반복되는 단일 리소스 요청보다 목록 API를 선호합니다.
- 자주 액세스하는 데이터, 특히 자주 변경되지 않는 메타데이터를 캐시합니다.
- 시간이 지남에 따라 요청을 균등하게 분산하여 트래픽 버스트를 방지합니다.
용량 한도 초과(CapacityLimitExceeded)
CapacityLimitExceeded 오류는 사용자 용량에서 소비된 컴퓨팅(용량 단위)이 구매한 Fabric SKU의 한도를 초과했음을 나타냅니다. 속도 제한과 달리 이 제한은 특정 호출자가 만드는 API 호출 수로 인해 발생하지 않습니다. 용량의 모든 워크로드에서 사용되는 전체 컴퓨팅을 반영합니다.
응답 본문 예제:
"Your organization's Fabric compute capacity has exceeded its limits. Try again later."
용량 스로틀링 처리
이 제한은 개별 요청 속도가 아니라 해당 용량에서 소비되는 전체 컴퓨팅 리소스에 좌우되므로 `Retry-After` 헤더는 적용되지 않으며, 용량의 컴퓨팅 사용량이 다시 한도 내로 내려갈 때까지는 즉시 재시도해도 성공할 가능성이 낮습니다. 애플리케이션은 다음을 수행해야 합니다.
- 나중에 지수 백오프와 함께 제한된 재시도 정책을 사용하여 요청을 다시 시도합니다.
- 오류가 지속되면 Fabric 용량을 확장하거나 스케일 아웃하는 것이 좋습니다.
용량 단위, SKU 및 Fabric 용량을 사용하는 방법에 대한 자세한 내용은 용량 크기 계획을 참조하세요.
요약
Microsoft Fabric REST API와 안정적인 통합을 구축하려면 강력한 오류 처리 및 효율적인 요청 패턴이 필요합니다. 오류 응답을 이해하고, 제한 신호를 적용하고, 요청 패턴을 최적화하면 복원력 있는 애플리케이션을 빌드할 수 있습니다.
관련 콘텐츠
추가 질문 또는 커뮤니티 지침은 Microsoft Fabric 커뮤니티를 참조하세요.