BLUEPRINT

제9장: 오류 처리

9.1 개요

프로토콜은 통일된 오류 처리 메커니즘을 정의하여, 스킬 소비자가 오류 원인을 정확히 이해하고 적절한 복구 조치를 취할 수 있도록 합니다.

9.2 오류 분류

오류 카테고리	오류 코드	HTTP 상태 코드	시나리오
유효성 검사 오류	VALIDATION_ERROR	N/A(로컬)	Schema Validator가 무효한 Skill Descriptor를 감지
인증 실패	AUTH_REQUIRED	401	보호된 스킬 호출 시 유효한 자격 증명 미제공
권한 부족	PERMISSION_DENIED	403	자격 증명은 유효하지만 스킬 접근 권한 없음
스킬 미발견	SKILL_NOT_FOUND	404	요청된 스킬 ID 또는 Descriptor URL이 존재하지 않음
실행 타임아웃	EXECUTION_TIMEOUT	408 / 504	스킬 실행이 설정된 타임아웃 초과
엔드포인트 도달 불가	ENDPOINT_UNREACHABLE	502 / 503	호출 엔드포인트에 연결 불가
버전 비호환	VERSION_INCOMPATIBLE	422	Skill Descriptor의 프로토콜 버전이 소비자와 비호환

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: Descriptor 수정 필요
AUTH_REQUIRED: 자격 증명 제공 필요
PERMISSION_DENIED: 권한 획득 필요
VERSION_INCOMPATIBLE: 소비자 업그레이드 필요