錯誤碼

AHP 使用 JSON-RPC 2.0 錯誤碼。除了標準 JSON-RPC 錯誤碼外，AHP 另在 -32000 到 -32099 的範圍內定義了應用程式專屬錯誤碼。

JSON Schema: errors.schema.json

標準 JSON-RPC 錯誤碼

這些錯誤碼由 JSON-RPC 2.0 規格所定義：

代碼	名稱	說明
`-32700`	剖析錯誤	無效的 JSON
`-32600`	無效請求	不是有效的 JSON-RPC 請求
`-32601`	找不到方法	未知的方法名稱
`-32602`	無效參數	無效的方法參數
`-32603`	內部錯誤	未指定的伺服器錯誤

AHP 應用程式錯誤碼

代碼	名稱	說明
`-32001`	`SessionNotFound`	所引用的工作階段 URI 不存在
`-32002`	`ProviderNotFound`	所請求的代理程式提供者未註冊
`-32003`	`SessionAlreadyExists`	具有給定 URI 的工作階段已存在
`-32004`	`TurnInProgress`	該操作要求沒有進行中的回合，但目前已有一個進行中
`-32005`	`UnsupportedProtocolVersion`	伺服器無法使用用戶端在 `InitializeParams.protocolVersions` 中提供的任何協定版本。JSON-RPC 錯誤的 `data` 欄位 MAY 是一個 `UnsupportedProtocolVersionErrorData`，宣告伺服器願意使用的協定版本。
`-32006`	`ContentNotFound`	所請求的內容 URI 不存在
`-32007`	`AuthRequired`	指令失敗，因為用戶端尚未針對必要的受保護資源進行驗證。JSON-RPC 錯誤的 `data` 欄位 MUST 是一個 `AuthRequiredErrorData`，描述需要驗證的資源。
`-32008`	`NotFound`	所請求的檔案、資料夾或 URI 不存在
`-32009`	`PermissionDenied`	用戶端未獲許可存取所請求的資源。當用戶端嘗試讀取或瀏覽允許集合之外的路徑（例如工作階段工作目錄或工作區根目錄之外）時，伺服器 SHOULD 回傳此錯誤。 JSON-RPC 錯誤的 `data` 欄位 MAY 是一個 `PermissionDeniedErrorData`，宣佈一個 `resourceRequest`，若獲准將可解鎖該操作。
`-32010`	`AlreadyExists`	目標資源已存在，且該操作不允許覆寫（例如帶有 `createOnly: true` 的 `resourceWrite`）。
`-32011`	`Conflict`	樂觀並行的先決條件失敗。當請求帶有的先決條件令牌不再與接收端目前的狀態相符時回傳 — 例如 `resourceWrite` 帶有已被並行寫入取代的 `ifMatch` etag。呼叫端 SHOULD 重新讀取資源（例如透過 `resourceResolve`），並決定是否要以新的令牌重試該操作，或將衝突呈現給使用者。

錯誤回應格式

所有錯誤回應都遵循 JSON-RPC 2.0 的錯誤格式：

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32002,
    "message": "沒有為提供者 'unknown' 註冊的代理程式",
    "data": {}
  }
}

data 欄位為 OPTIONAL，且 MAY 包含關於該錯誤的額外結構化資訊。其形狀不由協定定義。

具型別錯誤資料

少數錯誤碼會帶有具型別的 data 酬載。此對應關係由 AhpErrorDetailsMap 捕捉；具型別的 AhpError<C> 聯集會依據代碼縮窄 data。

`AuthRequiredErrorData`

在 AuthRequired（-32007）錯誤之 data 欄位中承載的詳細資料。

將受保護資源清單包裝在 { resources: [...] } 中，而非回傳裸陣列，如此一來未來版本可新增額外欄位而不破壞線路格式。

欄位	類型	說明
`resources`	ProtectedResourceMetadata[]	需要驗證的受保護資源。

`PermissionDeniedErrorData`

在 PermissionDenied（-32009）錯誤之 data 欄位中承載的詳細資料。

接收端 MAY 宣佈一個 resourceRequest 有效負載，描述若獲准將可解鎖該操作的存取。呼叫端接著 MAY 以該有效負載發出 resourceRequest 來協商存取。

欄位	類型	必要	說明
`request`	ResourceRequestParams	否	若透過 `resourceRequest` 獲准則可解鎖該操作的資源存取。當沒有任何特定的存取授權能解決此拒絕時省略（例如當資源根本無法存取時）。

`UnsupportedProtocolVersionErrorData`

在 UnsupportedProtocolVersion（-32005）錯誤之 data 欄位中承載的詳細資料。

欄位	類型	說明
`supportedVersions`	`string[]`	伺服器願意使用的協定版本。每個項目若非 SemVer `MAJOR.MINOR.PATCH` 字串（例如 `"0.1.0"`），即為 SemVer 範圍限制式（例如 `">=0.1.0 <0.3.0"` 或 `"^0.2.0"`）。

`AhpErrorDetailsMap`

將每個帶有結構化 data 的 AHP 錯誤碼對應到該資料的類型。

未出現在此對應中的錯誤碼，若非沒有 data 有效負載，即為帶有未指定的有效負載，呼叫端 SHOULD 將其視為 unknown。

欄位	類型	說明
`[AhpErrorCodes.AuthRequired]`	AuthRequiredErrorData
`[AhpErrorCodes.PermissionDenied]`	PermissionDeniedErrorData
`[AhpErrorCodes.UnsupportedProtocolVersion]`	UnsupportedProtocolVersionErrorData

`AhpErrorCode`

所有 AHP 應用錯誤碼的聯集類型。

(typeof AhpErrorCodes)[keyof typeof AhpErrorCodes]

`JsonRpcErrorCode`

所有 JSON-RPC 錯誤碼的聯集類型。

(typeof JsonRpcErrorCodes)[keyof typeof JsonRpcErrorCodes]

`AhpErrorCodeWithData`

帶有結構化 data 有效負載的 AHP 錯誤碼。

keyof AhpErrorDetailsMap

`AhpError`

一個型別化的 JSON-RPC 錯誤物件，其 data 會依 code 縮窄。

對 AhpErrorCode 聯集進行分配，因此對 code 縮窄即可顯現精確的 data 類型。對於列於 {@link AhpErrorDetailsMap} 中的錯誤碼，data 為必要；對於所有其他錯誤碼，data 為選用的 unknown。

function handle(err: AhpError) {
  if (err.code === AhpErrorCodes.PermissionDenied) {
    err.data.request; // typed as ResourceRequestParams | undefined
  }
}

C extends AhpErrorCode ? C extends keyof AhpErrorDetailsMap ? { /** 錯誤碼。 / readonly code: C; /* 人類可讀的錯誤訊息。 / readonly message: string; /* 由 [AhpErrorDetailsMap](#ahperrordetailsmap) 規定的結構化詳細資料有效負載。 / readonly data: AhpErrorDetailsMap[C]; } : { /* 錯誤碼。 / readonly code: C; /* 人類可讀的錯誤訊息。 / readonly message: string; /* 選用且未指定的詳細資料有效負載。 */ readonly data?: unknown; } : never

版本引入

上述所有錯誤碼皆於協定版本 1 引入。

錯誤碼 ​

標準 JSON-RPC 錯誤碼 ​

AHP 應用程式錯誤碼 ​

錯誤回應格式 ​

具型別錯誤資料 ​

AuthRequiredErrorData ​

PermissionDeniedErrorData ​

UnsupportedProtocolVersionErrorData ​

AhpErrorDetailsMap ​

AhpErrorCode ​

JsonRpcErrorCode ​

AhpErrorCodeWithData ​

AhpError ​

版本引入 ​

錯誤碼