规范

9. 错误处理

9.1 错误响应格式

所有错误响应 MUST 遵循统一结构：

interface ErrorResponse {
  error: {
    code: string;              // 必需，机器可读错误码
    message: string;           // 必需，人类可读错误描述
    details?: object;          // 可选，错误上下文
    retry?: {
      suggested_delay_ms: number;
      max_attempts: number;
    };
  };
}

9.2 错误分类

错误码	HTTP 状态	场景
`VALIDATION_ERROR`	N/A（本地）	Schema 验证失败
`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 错误示例

9.3.1 验证错误

{
  "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"
        }
      ]
    }
  }
}

9.3.2 认证失败

{
  "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"]
    }
  }
}

9.3.3 调用超时

{
  "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
    }
  }
}

9.4 重试策略

可重试错误（EXECUTION_TIMEOUT、ENDPOINT_UNREACHABLE）SHOULD 使用指数退避：

delay(n) = initial_delay × 2^(n-1)

不可重试错误（MUST NOT 自动重试）：

VALIDATION_ERROR
AUTH_REQUIRED
PERMISSION_DENIED
VERSION_INCOMPATIBLE