Core 오류

Failure로 분기했을 때 원인을 확인하는 타입입니다. 네트워크 실패, 시간 초과, 서버 오류, 플랫폼 오류처럼 기능 관점의 결과가 아닌 문제를 담습니다.

기능 관점의 결과는 여기에 담기지 않습니다. 각 메서드가 선언한 Outcome으로 분기하세요. 두 갈래의 차이는 결과 모델을 참조하세요.

HiveError

class — 네임스페이스 Hive.Axyl.Core

Failure의 상세 정보입니다. Failure.Problem 또는 IAxylResult.UntypedProblem으로 가져옵니다. 생성 후 변경할 수 없습니다.

프로퍼티

프로퍼티	타입	필수 여부	설명
Code	HiveErrorCode	Required	실패를 분류하는 코드입니다.
Message	string	Required	개발자가 원인을 확인하는 진단 메시지입니다. 영문입니다.
ExternalCode	string?	Optional	외부 시스템이나 플랫폼이 제공한 원본 오류 코드입니다. 예: HTTP 500, Net_Offline, BillingResponse:ITEM_ALREADY_OWNED.
TraceId	string?	Optional	서버 측에서 요청을 추적하는 식별자입니다. SDK의 네이티브 계층이 이 값을 전달한 경우에만 담기며, 그렇지 않으면 null입니다.
Details	IReadOnlyDictionary<string, string>?	Optional	플랫폼별 추가 키-값 정보입니다. 현재 Unity 구현에서는 채워지지 않으며 항상 null입니다.
Type	string?	Optional	오류 유형을 식별하는 URI입니다. 서버 응답에서 발생한 실패에만 담기며, Add-on 실패에서는 null입니다.
Instance	string?	Optional	오류가 발생한 요청 경로입니다. 서버 응답에서 발생한 실패에만 담기며, Add-on 실패에서는 null입니다.

먼저 Code로 실패 유형을 구분하세요. 원인을 조사할 때는 Message와 ExternalCode를 함께 확인합니다. 값별 처리 방법은 실패 원인별 처리를 참조하세요.

Message를 사용자에게 보여주지 마세요

Message는 개발자용 영문 진단 메시지이며, 현지화되지 않습니다. 네트워크 응답에서 온 메시지는 256자에서 잘립니다. 앱 사용자에게는 Code에 맞춰 앱이 준비한 문구를 보여주세요.

ToString()은 [Code] Message 형식으로 출력하며, ExternalCode가 있으면 뒤에 덧붙입니다.

HiveErrorCode

enum — 네임스페이스 Hive.Axyl.Core

실패를 분류하는 코드입니다. gRPC 상태 코드(0-16)와 값이 1:1로 대응합니다.

기능 관점의 결과는 이 열거형에 들어 있지 않습니다.

C# 멤버	값	설명
OK	0	전송 오류가 없음을 나타내는 값입니다. Failure에는 사용하지 않습니다.
Cancelled	1	코드에서 작업을 취소했습니다. 보통 CancellationToken에 의한 취소입니다.
Unknown	2	다른 코드로 분류할 수 없는 오류입니다.
InvalidArgument	3	요청 인자가 잘못되었습니다.
DeadlineExceeded	4	서버가 504로 응답했습니다. 요청 제한 시간이 지난 경우는 이 코드가 아니라 Unavailable로 반환됩니다.
NotFound	5	서버가 404로 응답했거나, Add-on이 요청한 상품이나 구매를 찾지 못했습니다. 기능 관점에서 리소스를 찾지 못한 경우는 이 코드가 아니라 Outcome으로 전달됩니다.
AlreadyExists	6	리소스가 이미 존재해 충돌했습니다.
PermissionDenied	7	인증은 되었지만 작업 권한이 없습니다.
ResourceExhausted	8	요청 제한, 할당량 또는 대기열 용량이 소진되었습니다.
FailedPrecondition	9	작업에 필요한 상태가 준비되지 않았습니다. SDK를 초기화하지 않은 경우가 여기에 해당합니다.
Aborted	10	동시성 충돌처럼 작업이 중단되었습니다.
OutOfRange	11	허용된 범위를 벗어났습니다.
Unimplemented	12	기능이 구현되지 않았거나 지원되지 않습니다.
Internal	13	SDK 또는 서버 내부 오류가 발생했거나 응답을 읽지 못했습니다.
Unavailable	14	네트워크 단절이나 서비스 일시 중단으로 호출을 완료하지 못했습니다. 재시도해도 되는지는 ExternalCode에 따라 다르므로 실패 원인별 처리를 참조하세요.
DataLoss	15	복구할 수 없는 데이터 손실 또는 손상이 발생했습니다.
Unauthenticated	16	인증 정보가 없거나 유효하지 않습니다.

RegistrationNotFoundException

class — 네임스페이스 Hive.Axyl.Core

HiveCore.Resolve<T>()에 등록되지 않은 타입을 요청했을 때 발생합니다. InvalidOperationException을 상속합니다.

프로퍼티	타입	필수 여부	설명
ContractType	Type	Required	등록되지 않은 타입입니다.

이 예외는 대부분 초기화 코드의 문제입니다. HiveBootstrap.Initialize의 등록 클로저에서 해당 모듈을 등록했는지 확인하세요.

Add-on은 지원 플랫폼에서만 등록되므로, Add-on을 가져올 때는 HiveCore.TryResolve<T>()를 사용해 등록 여부를 먼저 확인하세요.