Error Handling and the NSP SDK Exception Hierarchy - NSP

Every error raised by the nelieo-nsp SDK is a subclass of NSPError. Catching the right exception at the right level lets you distinguish between transient network failures, authentication problems, missing apps, and application-level action failures — and handle each one appropriately.

Exception Hierarchy

NSPError                              # Base class for all SDK errors
├── NSPConnectionError                # Daemon unreachable
├── NSPAuthError                      # Invalid or missing API key
├── NSPNotFoundError                  # App or PID not tracked
├── NSPRateLimitError                 # Too many requests
├── NSPTimeoutError                   # Request or probe timed out
├── NSPConfidenceTooLowError          # Probe confidence below action threshold
├── NSPActionError                    # Action dispatched but failed at app level
│   └── NSPIrreversibleNotConfirmedError  # verify=False on irreversible action
└── NSPServerError                    # Unexpected daemon error (5xx)

Base Error Fields

Every NSPError subclass exposes these three attributes:

e.message      # str  — human-readable description
e.code         # str  — machine-readable error code
e.status_code  # int  — HTTP status (0 for connection-level errors)

Exception Reference

NSPConnectionError — Daemon unreachable

When raised: The daemon is not running, is not listening on the configured host and port, or an existing connection was dropped during a request.HTTP status: 0 (no HTTP response received)Fields:

e.message — description of the connection failure
e.code — "connection_refused" or "connection_reset"
e.status_code — 0

How to handle:

try:
    apps = await client.list_apps()
except nsp.NSPConnectionError as e:
    print(f"Daemon unreachable: {e.message}")
    print("Start the daemon with: axon-daemon.exe run")
    raise

Common causes:

Daemon not started
NSP_PORT does not match AXON_SERVER__PORT in your daemon config
Firewall rule blocking localhost connections

NSPAuthError — Invalid or missing API key

When raised: The API key is absent, malformed, expired, or has been disabled on the daemon.HTTP status: 401Fields:

e.message — human-readable auth failure description
e.code — one of "missing_key", "invalid_key", "disabled_key"
e.status_code — 401

How to handle:

try:
    apps = await client.list_apps()
except nsp.NSPAuthError as e:
    print(f"Auth failed [{e.code}]: {e.message}")
    print("Generate a new key: axon-daemon.exe keygen")
    raise

Generate a fresh key and set it as an environment variable or pass it to NSPClient(api_key=...).

NSPNotFoundError — App or PID not tracked

When raised: The app name, app_id, or PID you requested does not exist in the daemon’s tracked list.HTTP status: 404Fields:

e.message — which resource was not found
e.code — "app_not_found" or "pid_not_found"
e.status_code — 404

How to handle:

try:
    session = await client.attach("Gmail")
except nsp.NSPNotFoundError:
    apps = await client.list_apps()
    available = [a.app_name for a in apps]
    print(f"App not found. Available: {available}")

    # If the app might still be launching, wait for it
    session = await client.wait_for_app("Gmail", timeout=60.0)

NSPRateLimitError — Too many requests

When raised: You have exceeded the daemon’s per-key rate limit for state reads or action dispatches.HTTP status: 429Fields:

e.message — rate limit description
e.code — "rate_limit_exceeded"
e.status_code — 429
e.retry_after — float — minimum seconds to wait before retrying

How to handle with exponential backoff:

import asyncio

async def with_backoff(coro_fn, max_retries: int = 5):
    """Call coro_fn(), retrying on rate-limit with exponential backoff."""
    for attempt in range(max_retries):
        try:
            return await coro_fn()
        except nsp.NSPRateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Honor the daemon's retry_after if provided
            wait = max(e.retry_after or 0, 2 ** attempt)
            print(f"Rate limited. Retrying in {wait:.1f}s "
                  f"(attempt {attempt + 1}/{max_retries})")
            await asyncio.sleep(wait)

Default limits: 100 state reads/sec and 10 actions/sec per API key. Adjust in axon.toml.

NSPTimeoutError — Request or probe timed out

When raised: A request exceeded NSPClient’s timeout setting, or a fresh probe cycle did not complete within the daemon’s probe timeout.HTTP status: 504Fields:

e.message — what timed out
e.code — "request_timeout" or "probe_timeout"
e.status_code — 504

How to handle:

try:
    # Fresh probes can be slow for CLR/JVM targets
    state = await client.get_state(pid, fresh=True)
except nsp.NSPTimeoutError:
    # Fall back to cached state
    state = await client.get_state(pid, fresh=False)
    print(f"Using cached state — confidence={state.confidence:.2f}")

NSPConfidenceTooLowError — Probe not ready

When raised: The probe’s confidence score is below the minimum required to execute the requested action. This prevents the SDK from acting on stale or incomplete state.HTTP status: 422Fields:

e.message — description including current and required confidence
e.code — "confidence_too_low"
e.status_code — 422
e.current_confidence — float — the probe’s current score
e.required_confidence — float — minimum score needed

When this happens:

The app was just detected and the first probe is not yet complete
The app navigated to a new view and confidence dropped temporarily
A native app with inherently variable confidence

How to handle:

try:
    await session.execute("send_reply", parameters={...}, verify=True)
except nsp.NSPConfidenceTooLowError as e:
    print(
        f"Confidence {e.current_confidence:.2f} below "
        f"required {e.required_confidence:.2f}"
    )
    # Wait for probe to warm up, then retry
    await asyncio.sleep(5.0)
    await session.refresh(fresh_probe=True)
    # Retry the action once
    await session.execute("send_reply", parameters={...}, verify=True)

NSPActionError — Action failed at the application level

When raised: The action was dispatched to the runtime but failed — either because the application rejected it, the action’s internal logic errored, or post-action verification did not pass.Fields:

e.message — human-readable failure description
e.code — machine-readable error code (e.g. "clr_invoke_timeout", "verification_failed")
e.action — str — name of the action that failed
e.verification_failed — bool — True if the action ran but verify_expression returned falsy

How to handle:

try:
    result = await session.execute(
        "send_reply",
        parameters={"thread_id": "msg_18821af3", "body": "On my way."},
        verify=True,
        verify_expression="inbox.sent_count > 0",
    )
except nsp.NSPActionError as e:
    print(f"Action '{e.action}' failed: {e.message}  code={e.code}")
    if e.verification_failed:
        print("  The action ran but post-action state did not match "
              "the verify_expression.")

NSPIrreversibleNotConfirmedError — Missing verify=True

When raised: You called session.execute() on an IrreversibleWrite action without explicitly setting verify=True. The SDK enforces this check locally before sending any request to the daemon — no network round-trip is wasted.Fields:

e.message — explanation of why the call was rejected
e.code — "irreversible_not_confirmed"
e.action — str — name of the irreversible action

How to handle:

# This raises NSPIrreversibleNotConfirmedError:
await session.execute("delete_thread", parameters={"thread_id": "msg_abc"})

# Correct — pass verify=True explicitly:
await session.execute(
    "delete_thread",
    parameters={"thread_id": "msg_abc"},
    verify=True,
    verify_expression="inbox.total_count < prev_total",
)

Comprehensive Try/Except Pattern

Use this template as the foundation for any production agent:

import asyncio
import nelieo_nsp as nsp

async def safe_execute(session: nsp.NSPSession, action: str, parameters: dict):
    """
    Execute an action with full error handling for every SDK exception class.
    Returns ActionResponse on success, or re-raises on unrecoverable errors.
    """
    for attempt in range(3):
        try:
            result = await session.execute(
                action,
                parameters=parameters,
                verify=True,
            )
            return result

        except nsp.NSPConnectionError:
            # Daemon went away — nothing we can do here
            print("❌ Daemon connection lost. Is axon-daemon running?")
            raise

        except nsp.NSPAuthError:
            # Key is invalid — not retriable without operator intervention
            print("❌ Invalid API key. Run: axon-daemon.exe keygen")
            raise

        except nsp.NSPNotFoundError:
            # App disappeared (process exited) — not retriable
            print(f"❌ App no longer tracked by daemon")
            raise

        except nsp.NSPConfidenceTooLowError as e:
            print(
                f"⚠ Confidence {e.current_confidence:.2f} < "
                f"required {e.required_confidence:.2f} — waiting 5s"
            )
            await asyncio.sleep(5.0)
            await session.refresh(fresh_probe=True)
            # loop continues to retry

        except nsp.NSPRateLimitError as e:
            wait = max(e.retry_after or 0, 2 ** attempt)
            print(f"⚠ Rate limited. Retrying in {wait:.1f}s...")
            await asyncio.sleep(wait)
            # loop continues to retry

        except nsp.NSPTimeoutError:
            print(f"⚠ Timeout on attempt {attempt + 1}. Retrying...")
            await asyncio.sleep(2.0)
            # loop continues to retry

        except nsp.NSPIrreversibleNotConfirmedError as e:
            # Programming error — must be fixed in code, not retried
            print(f"❌ Action '{e.action}' is irreversible. Set verify=True.")
            raise

        except nsp.NSPActionError as e:
            print(f"❌ Action '{e.action}' failed: {e.message}  code={e.code}")
            if e.verification_failed:
                print("  Action ran but post-action state did not match "
                      "verify_expression.")
            raise

    raise nsp.NSPError("Exceeded maximum retry attempts")


# Usage
async def main():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        session = await client.attach("Gmail")

        result = await safe_execute(
            session,
            "archive",
            {"email_id": session.get_str("inbox.emails[0].id")},
        )
        print(f"Archived: {result.success}  latency={result.latency_ms}ms")

asyncio.run(main())

Never silently swallow NSPConnectionError or NSPAuthError. These indicate conditions that require operator action and cannot be resolved by retrying.

​Exception Hierarchy

​Base Error Fields

​Exception Reference

​Comprehensive Try/Except Pattern

Exception Hierarchy

Base Error Fields

Exception Reference

Comprehensive Try/Except Pattern