Core result model

Hive Axyl SDK methods return call failures as result objects, not as exceptions. Result objects implement IAxylResult, and you branch on them with a switch statement instead of try/catch. Problems that require fixing app code are thrown as exceptions, and the conditions for them are listed in Exceptions.

Each method has its own result type. For example, CreateGuestAsync() returns AuthCreateGuestResult, which contains Success and the feature-specific results as nested classes.

Result branches

Every result type is divided into the following four branches.

Branch	Concrete type	Meaning	Handling
`Success`	`XxxResult.Success`	The call succeeded.	Use the response data in `Data`.
`Outcome`	`XxxResult.<result name>`	The call ran to completion, and a feature-level result has been determined. For server modules, the server determines the result; for Add-ons, the store or the operating system does.	Provide user guidance or an alternative flow for each result.
`UnknownOutcome`	`XxxResult.UnknownOutcome`	A new result that this SDK version does not know.	Log it, and then handle it conservatively as a failure.
`Failure`	`XxxResult.Failure`	The call could not be completed, for example because of a network disconnection, a timeout, or call cancellation, or the server responded but not with a feature-level result.	Check the cause with the HiveError in `Problem`.

Which Outcome each method declares is listed in the reference for that method.

Check with flags

In common handling code that cannot know the concrete type, distinguish the branches with the two flags of IAxylResult.

Branch	`IsSuccess`	`IsUntypedProblem`
`Success`	`true`	`false`
`Outcome`	`false`	`false`
`UnknownOutcome`	`false`	`false`
`Failure`	`false`	`true`

The two flags are never true at the same time. IsUntypedProblem being false does not mean the call succeeded, so you must branch on Outcome and UnknownOutcome separately by concrete type.

Branching example

Unity

AuthCreateGuestResult result = await auth.CreateGuestAsync(request);

switch (result)
{
    case AuthCreateGuestResult.Success success:
        // success.Data : GuestCreateResponseData
        break;

    // Branch only on the Outcomes declared by this method that the app handles.
    case AuthCreateGuestResult.IpBlocked:
        break;

    case AuthCreateGuestResult.Failure failure:
        HiveError err = failure.Problem;
        // err.Code, err.Message, err.ExternalCode
        break;

    case AuthCreateGuestResult.UnknownOutcome unknown:
        // Record unknown.Code and unknown.RawJson, and then handle it as a failure.
        break;

    // Safety net: Outcomes the app does not handle separately
    default:
        break;
}

UNKNOWN and FAILURE are not server values

UNKNOWN and FAILURE, shown as the wire codes of UnknownOutcome and Failure in the result case tables of the method references, are identifiers the SDK assigns, not values the server sends. The actual code the server sent is held in UnknownOutcome.Code and Failure.Problem.ExternalCode.

IAxylResult

interface — namespace Hive.Axyl.Core

The interface that every result object implements. Use it to handle results in a common way regardless of the module.

It is read-only. Only the result types the SDK generates implement it; it is not meant to be implemented by app code. Members may be added in minor releases.

Properties

Property	Type	Description
`IsSuccess`	`bool`	`true` if the call succeeded.
`IsUntypedProblem`	`bool`	`true` if the result is `Failure`. Feature-level `Outcome` results are not included.
`UntypedProblem`	`HiveError?`	The detailed information of `Failure`. It holds a value only when `IsUntypedProblem` is `true`.
`RawResponse`	`string?`	The original response body used to create this result.

UntypedProblem is the same value as Failure.Problem. If you branched by concrete type, Failure.Problem is easier to read; in common handling code that is independent of modules, UntypedProblem is more convenient.

Purpose of RawResponse

RawResponse is available in all four branches. It lets you read fields newly added by the server without regenerating the SDK. It is null only when no response body was received, such as with a transport failure.

This value is reference information for future compatibility. Do not use it as the basis for determining which result you have. Always branch based on the result code and the concrete type.

AxylResultBase

class — namespace Hive.Axyl.Core

The abstract base class of every result type the SDK generates. It implements IAxylResult and guarantees that only one of the four branches described above holds.

App code never needs to handle it directly. Refer to it only when you want to check where the common properties of the result types come from.

Marker interfaces

Use them to filter results of a particular nature at once, regardless of the module. Their namespace is always Hive.Axyl.Contracts.Result.

IUnknownOutcome

interface

Marks a new result code that the SDK does not know. The generated UnknownOutcome variants implement this interface.

Property	Type	Required	Description
`Code`	`string`	Required	The result code in the server response that the SDK did not recognize.
`RawJson`	`string`	Required	The original JSON body. Use it when the app needs to interpret the body itself.

Unity

if (result is IUnknownOutcome unknown)
{
    // Log unknown.Code and unknown.RawJson, and then handle it as a failure.
}

IUntypedProblem

interface

Marks a technical failure. This is the case where the request did not reach its destination, or a response was received but the SDK could not interpret it as a feature-level result. Network failures, transport timeouts, cancellation by a CancellationToken, and precondition violations of the native SDK (before initialization, unsupported platform) fall into this category.

It applies both to modules that call the server and to Add-ons. The generated Failure variants implement this interface.

Property	Type	Required	Description
`Problem`	HiveError	Required	The detailed information of the failure.

Unity

if (result is IUntypedProblem problem)
{
    ShowError(problem.Problem);
}

IUserCanceledOutcome

interface

Marks a result where the app user canceled by closing an OS or authentication provider screen themselves. Closing the Apple login dialog or canceling the Credential Manager sheet falls into this category.

It has no properties and is used only for type checks.

Cancellation by code is not this marker

This marker represents only user cancellation at the OS screen level. When code cancels with a CancellationToken or a session cancellation method, the result is classified as a Failure that holds the Cancelled code, and this marker is not attached.

Unity

if (result is IUserCanceledOutcome)
{
    // The user closed it directly, so do not show an error message.
}