ZeroLeaks SDK
Errors and Reliability
Handle typed SDK errors, rate limits, timeouts, cancellation, and failed scans.
Errors and Reliability
The SDK exports typed errors:
import {
ZeroLeaksAbortError,
ZeroLeaksError,
ZeroLeaksScanError,
ZeroLeaksTimeoutError,
} from "@zeroleaks/sdk";
try {
await zeroleaks.scans.run({ systemPrompt });
} catch (error) {
if (error instanceof ZeroLeaksScanError) {
console.error(error.scanId, error.details);
} else if (error instanceof ZeroLeaksAbortError) {
console.error("Local polling was aborted");
} else if (error instanceof ZeroLeaksTimeoutError) {
console.error("The request or polling operation timed out");
} else if (error instanceof ZeroLeaksError) {
console.error(error.status, error.code, error.requestId);
}
}HTTP errors
| Status | Meaning | Recommended behavior |
|---|---|---|
400 | Invalid request | Correct the named field before retrying |
401 | Missing, invalid, or revoked API key | Replace the key; do not retry automatically |
403 | Subscription or workspace limit | Upgrade or change account configuration |
404 | Resource is absent or inaccessible | Verify the ID and API-key owner |
429 | Rate limit exceeded | Wait until the supplied reset time |
500 / 503 | Service or deployment configuration error | Retry later with bounded backoff |
The SDK does not automatically retry scan-creation requests because retrying a non-idempotent request could create duplicate scans.
Runtime target exceptions are submitted to the active relay event and rethrown as ZeroLeaksScanError. The hosted workflow then fails with the same target error instead of silently scoring a partial run.
Abort local polling
const controller = new AbortController();
const pending = zeroleaks.scans.wait(scanId, {
signal: controller.signal,
});
controller.abort();Aborting a runtime scan or reaching its local timeout triggers best-effort cancellation of the hosted workflow. For other scan types, call scans.cancel(scanId), endpointScans.cancel(scanId), or runtimeScans.cancel(scanId) explicitly.