Results and recovery

Every awaited action returns the same outer shape:

{
    status = "succeeded", -- "failed" or "cancelled"
    ok = true,
    code = "ok",
    retryable = false,
    message = "...",
    data = {},
}

Read ok first. If it is false, use retryable to decide whether a new observation and a bounded retry make sense.

local result = hexis.await(handle, {timeout = 60})
if result.ok then
    return true
end

if result.retryable then
    hexis.sleep(1)
    return false
end

return nil

Common meanings

Code	What it tells Lua
`ok`	The action reached its documented success condition.
`busy`	A required control resource was owned by another action.
`timeout`	The caller's bounded wait ended. Do not assume the world changed.
`world_changed`	Evidence and work from the previous world are invalid.
`authority_lost`	The run no longer had permission to continue controlling the client.
`unreachable`	A complete search proved the destination unreachable.
`navigation_failed`	Navigation stopped without a complete unreachable proof.
`terrain_incomplete`	Required resident terrain was unavailable.
`target_lost`	The exact target could no longer be validated.
`gui_precondition_failed`	Screen, target, or guard evidence changed. Observe again.
`cancelled`	Cancellation won before the action's irreversible boundary.

The API registry lists every stable code. Action-specific guides explain what data contains and what success means for that action.

Retry from new evidence

Never retry an old GUI slot reference, entity reference, world generation, or block observation blindly. Observe again, check that the goal is still useful, then start a new bounded action.

Common meanings​

Retry from new evidence​

Common meanings

Retry from new evidence