BLUEPRINT

第九章：錯誤處理

9.1 概述

協定定義了統一的錯誤處理機制，確保技能消費者能夠準確理解錯誤原因並採取適當的復原措施。

9.2 錯誤分類

錯誤類別	錯誤碼	HTTP 狀態碼	情境
驗證錯誤	VALIDATION_ERROR	N/A（本機）	Schema Validator 偵測到無效的技能描述符
認證失敗	AUTH_REQUIRED	401	未提供有效憑證呼叫受保護技能
權限不足	PERMISSION_DENIED	403	憑證有效但無權存取該技能
技能未找到	SKILL_NOT_FOUND	404	請求的技能 ID 或描述符 URL 不存在
呼叫逾時	EXECUTION_TIMEOUT	408 / 504	技能執行超過設定的逾時時間
端點不可達	ENDPOINT_UNREACHABLE	502 / 503	呼叫端點無法連線
版本不相容	VERSION_INCOMPATIBLE	422	技能描述符的協定版本與消費者不相容

9.3 統一錯誤回應格式

所有錯誤回應遵循統一結構：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人類可讀的錯誤描述",
    "details": {},
    "retry": {
      "suggested_delay_ms": 0,
      "max_attempts": 0
    }
  }
}

欄位說明

欄位	型別	必要	說明
`error.code`	string	是	機器可讀的錯誤碼
`error.message`	string	是	人類可讀的錯誤描述
`error.details`	object	否	錯誤的詳細上下文資訊
`error.retry`	object	否	重試建議
`error.retry.suggested_delay_ms`	number	否	建議的重試延遲（毫秒）
`error.retry.max_attempts`	number	否	建議的最大重試次數

9.4 各類錯誤詳細說明

驗證錯誤

Schema Validator 偵測到無效文件時回傳：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Skill descriptor validation failed",
    "details": {
      "violations": [
        {
          "field": "/capability_type",
          "expected": "one of: plugin, api, knowledge, task",
          "actual": "unknown_type",
          "message": "Invalid enum value"
        },
        {
          "field": "/endpoint/url",
          "expected": "string (URI format)",
          "actual": null,
          "message": "Required field is missing"
        }
      ]
    }
  }
}

特點：

回傳所有違規欄位的列表（非僅第一個錯誤）
每個條目包含欄位路徑（JSON Pointer 格式）、期望值和實際值

認證失敗

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required to invoke this skill",
    "details": {
      "required_auth_type": "oauth2",
      "authorization_url": "https://example.com/oauth/authorize",
      "scopes": ["skill:invoke"]
    }
  }
}

特點：

包含所需的認證方式說明
協助消費者自動完成認證流程

呼叫逾時

{
  "error": {
    "code": "EXECUTION_TIMEOUT",
    "message": "Skill execution exceeded the configured timeout of 30000ms",
    "details": {
      "timeout_ms": 30000,
      "elapsed_ms": 30001
    },
    "retry": {
      "suggested_delay_ms": 5000,
      "max_attempts": 3
    }
  }
}

特點：

包含建議的重試延遲和最大重試次數
消費者可據此實作自動重試

端點不可達

{
  "error": {
    "code": "ENDPOINT_UNREACHABLE",
    "message": "Failed to connect to skill endpoint",
    "details": {
      "endpoint_url": "https://api.example.com/skills/translate/invoke",
      "reason": "Connection refused"
    },
    "retry": {
      "suggested_delay_ms": 2000,
      "max_attempts": 5
    }
  }
}

版本不相容

{
  "error": {
    "code": "VERSION_INCOMPATIBLE",
    "message": "Protocol version 2.0.0 is not compatible with consumer version 1.x",
    "details": {
      "descriptor_version": "2.0.0",
      "consumer_supported_range": "1.x.x",
      "upgrade_url": "https://skill-sharing.org/upgrade-guide"
    }
  }
}

9.5 重試策略

指數退避

對於可重試的錯誤（逾時、端點不可達），建議使用指數退避策略：

延遲 = initial_delay × 2^(attempt - 1)

範例（initial_delay = 1000ms）：

第 1 次重試：1000ms
第 2 次重試：2000ms
第 3 次重試：4000ms
第 4 次重試：8000ms

不可重試的錯誤

以下錯誤不應重試：

VALIDATION_ERROR：需修復描述符
AUTH_REQUIRED：需提供憑證
PERMISSION_DENIED：需取得權限
VERSION_INCOMPATIBLE：需升級消費者