errors library

Classes

AimuxErrorCode
Machine-readable codes. Values match C aimux_error_code_t / Go Code. 16 variant codes: 1–17 (1 is the catch-all; 4 is retired). A code outside that set is a header/library mismatch and fails with StateError, not an error type. Every HTTP-shaped failure arrives as apiCall, classified by AimuxException.status (401 auth, 404 model, 429 rate limit; -1 = no HTTP response was ever observed — a missing API key, an error built without a request, or a transport failure).

Enums

RecordingErrorCode
Code of a RecordingException. Dart keeps six values independent of the C transport codes 100..105. Only writerGone, flushTimeout and write are reachable from a flush.
RetryErrorReason
Why a RetryError stopped retrying (core serde camelCase wire names).

Properties

aimuxDropHandle → void Function(int)
aimux_drop_handle — releases a model / provider handle. Lazy, as above. (Never for errors: those go through aimux_error_free.)
final
aimuxFreeString → void Function(Pointer<Utf8>)
aimux_free_string — frees aimux-allocated result strings. Lazily initialized so pure-Dart tests that never produce a native string do not dlopen the library.
final

Functions

checkJson(String? json, String param, {bool emptyIsDefault = false}) → void
Validate a caller-supplied raw JSON string before it crosses the C C ABI; throws FormatException naming param (source) on bad syntax. Null passes through (optional parameters); empty/blank is rejected like the FFI does for REQUIRED params, unless emptyIsDefault — pass it for every OPTIONAL JSON param (nullable in the Dart signature: config_json of provider/router/moa, opts_json of embed / file upload / transcription), where the FFI treats NULL/empty as "use defaults".
checkPortable(Object? value, String param, [int depth = 0]) → void
Reject a JSON value that jsonDecode/jsonEncode accept but serde_json on the Rust side does not. Divergences (all three verified against serde_json 1.0.151):
construct2(String apiKey, String modelId, String? baseUrl, Pointer<Void> plain(Pointer<Utf8>, Pointer<Utf8>, Pointer<Uint64>), Pointer<Void> withBase(Pointer<Utf8>, Pointer<Utf8>, Pointer<Utf8>, Pointer<Uint64>)) → int
Shared constructor for (api_key, model_id[, base_url], out_handle) providers.
encodeJson(Object? value, String param) → String
jsonEncode for a caller-supplied value the binding serializes itself (prompts, call options, ProviderConfig) — pre-validated with the same rule checkJson applies to caller-supplied JSON text, because nothing downstream would check it.
expectAimuxError(Pointer<Void> e, String context) → void
Decode the aimux_error_t * e returned by a call that can fail in AiMuxError ([AiMuxError] in aimux-ffi.h). NULL → returns (success). Codes 1..17 become AimuxException; 200..206 become StateError. The returned error is always freed.
expectFfiError(Pointer<Void> e, String context) → void
Same for calls that only expose C ABI failures ([C ABI]): message only → invariant StateError.
expectRecordingError(Pointer<Void> e, String context) → void
Same as expectAimuxError for calls that can fail in the recorder ([RecordingError]): 100..105 → RecordingException; 200..206 → invariant StateError.
openAimuxLibrary() → DynamicLibrary
Opens the aimux-ffi native library for the current platform.
takeHandle(Pointer<Void> fn(Pointer<Uint64> out), String context) → int
Run fn with a zeroed uint64_t *out_handle, expectAimuxError the returned error, and hand back the handle.
takeString(Pointer<Void> fn(Pointer<Pointer<Utf8>> out), String context) → String
Run fn with a NULL char **out_json, expectAimuxError the returned error, copy the owned C string out and free it.
toCString(String s) → Pointer<Utf8>
toNativeUtf8 with the two checks a C string needs and a Dart String does not enforce, applied to every string parameter that crosses the ABI (model ids, api keys, base URLs, dir paths, base64 payloads, media types, JSON text):
toCStringOrNull(String? s) → Pointer<Utf8>
toCString for an optional argument: nullptr for null (the FFI reads NULL as "absent"). Callers still free a non-NULL result.
withUtf8<T>(String s, T fn(Pointer<Utf8>)) → T
Run fn with a temporary native UTF-8 copy of s; always frees it.

Exceptions / Errors

AimuxException
Base class for aimux AiMuxErrors only.
AimuxTimeoutError
Request timed out. (Prefixed to avoid shadowing dart:async TimeoutError.)
APICallError
Provider API call failed (AI SDK APICallError analogue) — every HTTP-shaped failure. status is the classification (401 auth, 404 model, 429 rate limit + retryMs); -1 means no HTTP response was ever observed — a missing API key, an error built without a request, or a transport failure. Read retryable to decide on a retry; status cannot tell those two apart.
InvalidArgumentError
Invalid argument (null args, invalid or expired handles, …).
InvalidPromptError
Invalid prompt.
InvalidResponseDataError
Invalid / malformed response data (streaming or decode failure).
InvalidToolInputError
The model produced tool arguments that fail to parse or validate.
JSONParseError
JSON parse / serialize failure.
NoSuchModelError
No such model in registry / catalogue.
NoSuchProviderError
No such provider name.
NoSuchToolError
The model called a tool that is not in the supplied tool set.
OtherError
Unclassified failure (AIMUX_E_OTHER).
RecordingException
Recording failure reported by initRecording() / recordingTryFlush(). NOT an AimuxException — the recorder is a separate subsystem with its own closed error set.
RequestAbortedError
Request aborted (not DOM AbortError).
RetryError
Retrying stopped (AIMUX_E_RETRY): reason says why, message carries the composed summary ("Failed after N attempts…"), and errors keeps the per-attempt history, oldest first — each entry is itself a fully decoded AimuxException (an APICallError keeps its whole detail set; a nested RetryError recurses).
TokenExpiredError
Access token expired.
ToolCallRepairError
A repairToolCall hook itself failed.
UnsupportedFunctionalityError
Unsupported functionality.