SDK reference

Reference material for the SDK's exception types, the HTTP error codes the API returns, and the SDK's behavioral options. For the limits that terminate an agent, see Limits & budgets.

Exceptions #

AgentKavach raises a small, typed set of exceptions when an agent is terminated. A cost budget raises BudgetExceededError. The guardrail and per-instance limits raise a subclass of GuardrailError, so a single except GuardrailError clause catches all of them, or you can catch a specific type. When the AgentKavach backend stops the agent (tier agent-limit, org daily-limit, org budget, or a dashboard Kill) the SDK raises IngestRejectedError — a BudgetExceededError subclass carrying the stop code on .reason, so existing handlers keep catching it while new code can tell a backend stop apart from a real budget kill.

Exception	Base class	Raised when
`BudgetExceededError`	`Exception`	A cost budget (daily, monthly, total, or org) is reached.
`IngestRejectedError`	`BudgetExceededError`	The backend rejects event ingest for this agent (`tier_agent_limit`, `daily_limit`, `org_budget_exceeded`). Calls pause to avoid untracked spend; the code is on `.reason`.
`TokenLimitError`	`GuardrailError`	`max_tokens_per_run` is reached.
`RuntimeLimitError`	`GuardrailError`	`max_runtime_seconds` is reached.
`CallLimitError`	`GuardrailError`	`max_calls_per_run` is reached.
`LoopDetectedError`	`GuardrailError`	A repeating call pattern trips loop detection.

python

from agentkavach.exceptions import (
    BudgetExceededError,
    GuardrailError,
    IngestRejectedError,
    TokenLimitError,
)

try:
    response = guard.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except TokenLimitError as e:
    print(f"Tokens: {e.spent}/{e.limit}")
except GuardrailError as e:
    print(f"Guardrail tripped: {e}")
except IngestRejectedError as e:
    print(f"Backend stopped the agent: {e.reason}")  # before BudgetExceededError
except BudgetExceededError as e:
    print(f"Budget reached: {e.spent}/{e.limit}")

Only termination errors propagate

These exceptions are the only ones AgentKavach raises on purpose. All other internal errors are caught and logged so they never block an LLM call, unless you opt into fail_on_error below.

HTTP error codes #

Separate from the exceptions above, the API returns these HTTP status codes. The SDK surfaces them when it talks to the AgentKavach backend.

Code	Name	Cause	Resolution
`401`	Unauthorized	Invalid, missing, or revoked API key.	Check the `api_key` you passed to the constructor. Keys are `ak_prod_`, `ak_dev_`, or `ak_local_`.
`403`	Forbidden	Subscription cancelled or expired.	Reactivate from the dashboard or call `POST /v1/billing/reactivate`.
`422`	Validation error	Request body fails schema validation.	Ensure required fields are present and correctly typed.
`429`	Too many requests	Daily event quota or burst rate exceeded.	Wait until `resume_at` or upgrade your tier.

on_kill kill reasons #

An on_kill callback that declares a parameter receives why the agent was stopped, so a teardown can log or page with the real cause instead of assuming a budget kill. Zero-argument callbacks keep working unchanged — declaring the parameter is the opt-in.

Reason	Passed when
`"cost"`	A cost budget (daily, monthly, total, or org) reached 100%.
`"tokens"` / `"duration"` / `"calls"` / `"loop"`	The corresponding per-run guardrail fired.
`"tier_agent_limit"`, `"daily_limit"`, `"org_budget_exceeded"`, `"backend_rejected"`	The backend stopped the agent — same codes as `IngestRejectedError.reason`.
`"internal_error"`	An internal SDK error killed the agent under `fail_on_error=True`.

python

def emergency_stop(reason):  # declare a parameter to receive the reason
    print(f"agent stopped: {reason}")  # "cost", "tier_agent_limit", ...

guard = AgentKavach(
    provider="openai",
    api_key="ak_prod_...",
    llm_key="sk-...",
    budget=Budget.daily(10),
    on_kill=emergency_stop,
)

fail_on_error #

By default AgentKavach is fail-open: an internal SDK error (network, parsing, and similar) never blocks your LLM call. Set fail_on_error=True to raise on those internal errors instead, trading availability for stricter enforcement.

python

guard = AgentKavach(
    provider="openai",
    api_key="ak_prod_...",
    llm_key="sk-...",
    budget=Budget.daily(50),
    fail_on_error=True,
)

Changes failure semantics

With fail_on_error=True, an internal AgentKavach error raises and your call does not complete. Use it only when you would rather stop than risk an unmetered call.

save_prompts #

Prompt text is not stored by default. Set save_prompts=True to record prompt text in the dashboard events table for debugging. While it is off, the dashboard shows that prompt logging is disabled.

python

guard = AgentKavach(
    provider="openai",
    api_key="ak_prod_...",
    llm_key="sk-...",
    budget=Budget.daily(50),
    save_prompts=True,
)

Privacy

Prompt text is never stored unless you explicitly enable it. See the privacy policy for retention details.