BLUEPRINT

第9章：エラー処理

9.1 概要

プロトコルは統一されたエラー処理メカニズムを定義し、スキル消費者がエラー原因を正確に理解し、適切な回復措置を講じられるようにします。

9.2 エラー分類

エラーカテゴリエラーコードHTTPステータスコードシナリオ
バリデーションエラーVALIDATION_ERRORN/A（ローカル）Schema Validatorが無効なSkill Descriptorを検出
認証失敗AUTH_REQUIRED401保護されたスキルの呼び出し時に有効な資格情報が未提供
権限不足PERMISSION_DENIED403資格情報は有効だがスキルへのアクセス権がない
スキル未検出SKILL_NOT_FOUND404リクエストされたスキルIDまたはDescriptor URLが存在しない
実行タイムアウトEXECUTION_TIMEOUT408 / 504スキル実行が設定されたタイムアウトを超過
エンドポイント到達不能ENDPOINT_UNREACHABLE502 / 503呼び出しエンドポイントに接続不可
バージョン非互換VERSION_INCOMPATIBLE422Skill Descriptorのプロトコルバージョンが消費者と非互換

9.3 統一エラーレスポンス形式

すべてのエラーレスポンスは統一された構造に従います：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "人間が読めるエラー説明",
    "details": {},
    "retry": {
      "suggested_delay_ms": 0,
      "max_attempts": 0
    }
  }
}

フィールド説明

フィールド型必須説明
error.codestringはい機械可読なエラーコード
error.messagestringはい人間が読めるエラー説明
error.detailsobjectいいえエラーの詳細コンテキスト情報
error.retryobjectいいえリトライ提案
error.retry.suggested_delay_msnumberいいえ推奨リトライ遅延（ミリ秒）
error.retry.max_attemptsnumberいいえ推奨最大リトライ回数

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：Descriptorの修正が必要
  • AUTH_REQUIRED：資格情報の提供が必要
  • PERMISSION_DENIED：権限の取得が必要
  • VERSION_INCOMPATIBLE：消費者のアップグレードが必要