SynheartNativeError class

A structured failure reported by the native runtime.

Every runtime failure has this shape, whether it arrived inside a sync envelope ({"ok": false, "error": {...}}) or was read back after a call that returned null, false or a non-zero code. Branch on code and recovery; show message; log hint and errorId. Internal detail (server bodies, paths, tokens) never reaches here: it stays in the native diagnostic log, on the line tagged with the same errorId.

Every field beyond code, message and retryable is optional in both directions: an older runtime never sends it, and a newer SDK must not assume it.

Constructors

SynheartNativeError({required String code, required String message, bool retryable = false, String? reason, int? retryAfterMs, Map<String, dynamic>? detail, String? owner, String? recovery, String? recoveryCall, String? hint, String? op, String? errorId, Map<String, dynamic>? report})
const
SynheartNativeError.fromMap(Map<String, dynamic> error)
Parse a native error object. Missing or mistyped fields fall back to a safe shape, so a malformed payload never throws here.
factory
SynheartNativeError.unknown()
Fallback used when a failure is known but its payload is missing or malformed.
factory

Properties

argument → String?
On INVALID_ARGUMENT: the rejected parameter's name, e.g. batch_json.
no setter
code → String
Stable machine-readable code, e.g. CONSENT_REQUIRED, NETWORK. Treat an unrecognised value as UNKNOWN.
final
detail → Map<String, dynamic>?
Diagnostics — phase, http_status, server_code, argument. Log it; branch on argument if you need the parameter, never on the map shape.
final
errorId → String?
Eight hex digits matching the native diagnostic log line for this failure. Put it in bug reports and "report a problem" UI.
final
hashCode → int
The hash code for this object.
no setterinherited
hint → String?
One developer-facing sentence on the cause. Log it; it may be reworded in any runtime release, so never branch on it.
final
isMisconfigured → bool
The attestation setup is wrong; a developer has to fix it.
no setter
isPolicyRefusal → bool
The server refused this device permanently.
no setter
isRuntimeBug → bool
A defect in the runtime, not in the integrating code. Report it.
no setter
isUnsupported → bool
The device can never attest (no Play Services, emulator, Simulator). Degrade to local-only and stop asking, including across relaunches.
no setter
message → String
End-user-safe message. Show it; never parse it.
final
op → String?
The native entry point that failed, e.g. synheart_core_start_session.
final
owner → String?
Raw owner token; see ownerKind.
final
ownerKind → NativeErrorOwner
Who can resolve this failure.
no setter
reason → String?
Closed-set token narrowing the cause, or null when there is none.
final
recovery → String?
Raw recovery token; see recoveryKind.
final
recoveryCall → String?
The exact native function that performs recovery, when one does, e.g. synheart_core_grant_consent. Agents should read this, not hint.
final
recoveryKind → NativeErrorRecovery
What to do about it.
no setter
report → Map<String, dynamic>?
runtime_version and abi, present only when the runtime itself is at fault (ownerKind is NativeErrorOwner.runtime).
final
retryable → bool
Whether retrying the same call unchanged may succeed.
final
retryAfterMs → int?
Suggested backoff before retrying. Null unless retryable.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited