適用於：合作夥伴中心 |合作夥伴中心推薦
適當的角色：轉介管理員 |推薦使用者
合作夥伴中心轉介 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 | 超過頻寬限制 | 因超過最大頻寬上限，客戶端應用程式被限制速度。 您的應用程式可以在一段時間后再次重試要求。 |
錯誤資源類型
錯誤回應是單一 JSON 物件，其中包含名為錯誤的單一屬性。 此物件會包含錯誤的所有詳細資料。 您可以使用這裡傳回的資訊，而不使用 HTTP 狀態碼，或者也可以同時使用兩者。
下表和程式代碼範例描述錯誤回應的架構。
| 名稱 | 類型 | 描述 |
|---|---|---|
| 程式碼 | 字串 | 總是返回。 表示所發生錯誤的類型。 非空值。 |
| 訊息 | 字串 | 總是返回。 詳細說明錯誤，並提供更多偵錯資訊。 非 Null 無空白。 最大長度為 1,024 個字元。 |
| 內部錯誤 | 物體 | 選擇性。 另一個錯誤物件，其中包含有關錯誤發生之更具體的資訊。 |
| innerError.code | 數值字串 | 如果 innerError 為非 Null，則一律傳回 。 在頂端錯誤碼值下提供更具體的錯誤碼資訊。 |
| 內部錯誤.訊息 | 字串 | 如果 innerError 為非 Null，則一律傳回 。 在頂端錯誤訊息字串下提供更具體的錯誤訊息。 |
| 內部錯誤.詳細資訊 | 陣列物件 | 選擇性。 包含更多關於錯誤的詳細資訊。 主要適用於輸入驗證錯誤。 |
| 目標 | 字串 | 選擇性。 錯誤來源的目標。 |
範例錯誤回應
{
"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 屬性
code 屬性包含下列其中一個可能的值。 應用程式應準備好處理其中任何一項錯誤。
| 代碼 | Http 狀態代碼 | 描述 |
|---|---|---|
| invalidRequest | 400 | 要求的格式錯誤或不正確。 |
| unauthenticated | 401 | 呼叫端未通過驗證。 |
| accessDenied | 403 | 呼叫端沒有執行此動作的權限。 |
| itemNotFound | 404 | 找不到資源。 |
| 資源已修改 | 409 | 自從呼叫端上次讀取後，要更新的資源已變更，通常是 eTag 不相符。 |
| 前提條件失敗 | 412 | 要求中提供的前置條件（例如 if-match 標頭）不符合資源的目前狀態。 |
| generalException | 500 | 發生未指定的錯誤。 |
| serviceNotAvailable | 503 | 無法使用服務。 請在延遲一段時間後再次嘗試要求。 可能會有 Retry-After 標頭。 |
Message 屬性
位於根目錄的 message 屬性含有要給開發人員閱讀的錯誤訊息。 錯誤訊息不會當地語系化，而且不應該直接向用戶顯示。 您的程式代碼不應該只檢查 message 值，因為它們可以隨時變更，而且通常包含失敗要求特有的動態資訊。 您應該針對屬性中 code 傳回的錯誤碼撰寫程式代碼，然後取得更多詳細數據，將其與消息正文結合。
InnerError 物件
innererror物件可能會以遞歸方式包含更多innererror具有更特定錯誤碼的物件。 用戶端應用程式在處理錯誤時，應該遍歷所有可用的錯誤碼，並選擇使用他們能理解的最詳細錯誤碼。
您的應用程式在巢狀 innererror 物件中可能會遇到一些錯誤。 應用程式不需要處理這些錯誤，但如果有選擇，就可以這麼做。 服務可能會新增錯誤碼或隨時停止傳回舊錯誤碼，因此所有應用程式都必須能夠處理 [基本錯誤碼]。
錯誤碼
以下是 API 所傳回的錯誤碼：
| HTTP 狀態 | HTTP 錯誤碼 | 錯誤碼 | 描述 |
|---|---|---|---|
| 錯誤請求 | 400 | 99901 | 無效的輸入 |
| 未經授權 | 401 | 99902 | 未經授權的存取 |
| 錯誤請求 | 400 | 99903 | 遺漏輸入 |
| 未找到 | 404 | 99904 | 找不到資源 |
| 內部伺服器錯誤 | 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 | 已透過另一個要求修改的資源 |
| 前置條件失敗 (PreConditionFailed) | 412 | 99918 | 要求中提供的前置條件（例如 if-match 標頭）不符合資源的目前狀態。 |
| 錯誤請求 | 400 | 99919 | 無效的轉介資格，無法更新 |
| 內部伺服器錯誤 | 500 | 99999 | 處理要求時的一般例外狀況 |