Skip to main content

​
ApieError

The SDK throws ApieError for client-side failures: registration errors, Enforce blocks, approval timeouts, and ingest failures. 
import { ApieError } from "@apie-sh/sdk";

try {
  await apie.withTool({ ... }, async () => deploy());
} catch (error) {
  if (error instanceof ApieError) {
    console.error(error.message, error.code);
  }
}

​
Guardrail failure modes

When guardrail evaluation fails (network error, timeout), guardFailureMode controls behavior:
ModeBehavior
fail_openAllow the action (default)
fail_closedTreat as blocked
throwThrow ApieError immediately
Configure in Configuration reference.

​
Guard decisions

In Enforce mode, withTool throws when:
DecisionError
blockGuard blocked the action
require_approval + rejectedApproval rejected
require_approval + timeoutApproval timed out
In Monitor mode, no errors are thrown for guardrail decisions.

​
MCP JSON-RPC error codes

When using the MCP proxy in Enforce mode:
CodeMeaning
-32001Guardrail blocked the tool call
-32002Approval denied or timed out
The MCP host receives these as JSON-RPC errors. The tool call is not forwarded to upstream.

​
Queue errors

onError settingBehavior
silentSwallow flush errors
warnLog warning (default)
throwThrow on flush failure

​
Event validation

Use validateEvents to check payloads before sending: 
const result = await apie.validateEvents([event]);
// result.previews[].validation_status: "valid" | "invalid"
// result.previews[].warnings: string[]

​
Disabled client

When enabled: false, the client never throws for network errors — all operations are no-ops with synthetic IDs.

​
Next steps

Diagnose your setup

Debug connection issues.

Enforce guardrails

Enforce mode behavior.