簡介
本文將協助你了解並排除 Microsoft Fabric REST API 常見的錯誤。 它說明了服務所使用的標準錯誤格式，並提供解決最常遇到的 HTTP 狀態碼的指引。
了解 Microsoft Fabric 錯誤回應
當處理對 Microsoft Fabric REST API 的請求時發生錯誤，服務會在回應主體中回傳一個標準 ErrorResponse 物件。
在排除故障時，務必擷取並記錄 requestId，因為它能唯一識別請求，且在聯絡 Microsoft 支援時是必須的。 請求 ID 同時存在於回應主體與回應標頭中。
重要
errorCode價值是穩定且基於合約的。- 人類可
message讀的文字可能會隨時間改變，且不應以程式化方式解析。
ErrorResponse 架構
| 名稱 | 類型 | 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 會基於兩個不同的原因傳回 429 狀態碼，而每個原因都可由回應主體中的不同 errorCode 識別。
常見的根本原因
| 錯誤碼 | Description | 解決辦法 |
|---|---|---|
RequestBlocked |
請求速率超過了服務的限速限制。 | 請等標頭上指定的 Retry-After 時間再重試。 請參見 您的應用程式中處理速率限制。 |
CapacityLimitExceeded |
您的容量所耗用的運算資源（容量單位）已超出所購買 Fabric SKU 的限制。 | 請稍後再重試該請求。 請參閱「處理容量節流」。 |
速率限制（RequestBlocked）
錯誤 RequestBlocked 表示請求速率超過服務的限速限制。
- 調節是根據呼叫者身份強制執行的。
- 頻率限制通常在一分鐘的時間窗口內評估。
重試時序資訊
當發生速率限制時，重試資訊會在兩個位置提供：
回應主體（
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 社群