Error handling and recovery

Revo 3 SDK v2.x exposes structured SdkError. Use code, operation effect, and recovery requirement for application logic; the text message is diagnostic context.

Fields to log

• Error code and message.
• operation_effect and recovery_requirement.
• Device identity, transport, port, SDK version, and firmware version.
• Final MotionHandle state for motion commands.

Recovery decision

Condition	Action
Invalid parameter or layout	Correct input; do not retry unchanged
Temporary read failure with a valid connection	Apply bounded backoff to reads
Write is confirmed not applied	Retry only when the recovery requirement allows it
operation_effect = Indeterminate	Read device state; do not retry directly
Connection is invalid	Close old objects, reconnect, and repeat preflight
Device fault or reset required	Stop motion flow and follow recovery requirements

Log SDK and firmware versions, device identity, transport, command, final MotionHandle state, and structured error fields. Bound both retry count and total recovery time. See types, enums, and errors.

Python pattern

try:
    handle = await hand.motion.move_joint(0, 20.0, duration=1.0)
    result = await handle.wait(timeout=3.0)
except sdk.SdkError as error:
    if error.operation_effect == sdk.OperationEffect.Indeterminate:
        state = await hand.state.snapshot()
        report_indeterminate_result(state)
    raise

Prevent multiple coroutines from recovering the same Hand at the same time.