Error Codes

HTTP status codes returned by the AgentKavach API and SDK exceptions you may encounter.

HTTP Error Codes #

The AgentKavach API uses standard HTTP status codes. Below are the error codes you may encounter:

Code	Name	When	What To Do
`401`	Unauthorized	Invalid, missing, or revoked API key	Check `api_key` or `AGENTKAVACH_API_KEY` env var. Keys start with `cg_`.
`403`	Forbidden	Subscription cancelled or expired	Reactivate via dashboard or `POST /v1/billing/reactivate`
`422`	Validation Error	Invalid request body	Check request schema in API Reference
`429`	Too Many Requests	Daily event limit or burst rate exceeded	Wait for reset (check `resume_at`) or upgrade tier

SDK Exceptions #

The AgentKavach SDK raises specific exceptions depending on which limit was hit. Some exceptions propagate to your code; others are swallowed silently (fail-open design).

Exception	When	Propagates?
`BudgetExceededError`	Budget limit reached	Yes — always
`TokenLimitError`	`max_tokens_per_run` exceeded	Yes
`CallLimitError`	`max_calls_per_run` exceeded	Yes
`RuntimeLimitError`	`max_runtime_seconds` exceeded	Yes
`LoopDetectedError`	Repetitive call pattern	Yes
`RateLimitedError`	AgentKavach API rate limit	No — SDK logs warning, LLM call continues
Internal errors	Any other SDK failure	No — fail-open, LLM call continues

Handling Exceptions #

Wrap your calls in a try/except block to handle each exception type:

python

from agentkavach import AgentKavach
from agentkavach.exceptions import (
    BudgetExceededError,
    TokenLimitError,
    CallLimitError,
    RuntimeLimitError,
    LoopDetectedError,
)

guard = AgentKavach(provider="openai", api_key="cg_...", llm_key="sk-...")

try:
    response = guard.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )
except BudgetExceededError as e:
    print(f"Budget exceeded: {e}")
    # Budget is exhausted — stop the agent or switch to a cheaper model
except TokenLimitError as e:
    print(f"Token limit hit: {e}")
    # Too many tokens in this run — summarize context and retry
except CallLimitError as e:
    print(f"Call limit hit: {e}")
    # Too many API calls in this run — wrap up the agent loop
except RuntimeLimitError as e:
    print(f"Runtime limit hit: {e}")
    # Agent has been running too long — force completion
except LoopDetectedError as e:
    print(f"Loop detected: {e}")
    # Agent is stuck in a loop — break and report

ℹ️ Fail-open design

AgentKavach is designed to never block your LLM calls due to internal errors. Only explicit budget/guardrail violations (the exceptions listed above) propagate to your code. If the AgentKavach API is unreachable or returns an unexpected error, the SDK logs a warning and lets the LLM call proceed normally.