Error Codes

HTTP status codes returned by the API and exceptions raised by the SDK.

HTTP error codes #

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.	Compare the payload to the API Reference.
`429`	Too many requests	Daily event quota or burst rate exceeded.	Wait until `resume_at` or upgrade your tier.

SDK exceptions #

The SDK raises seven exceptions. Five reach your code. Two do not.

Exception	Triggered by	Propagates
`BudgetExceededError`	Budget limit reached.	Yes
`TokenLimitError`	`max_tokens_per_run` exceeded.	Yes
`CallLimitError`	`max_calls_per_run` exceeded.	Yes
`RuntimeLimitError`	`max_runtime_seconds` exceeded.	Yes
`LoopDetectedError`	Repeating call pattern detected.	Yes
`RateLimitedError`	AgentKavach API rate limit.	No. The SDK logs a warning. The LLM call continues.
Internal errors	Any other SDK failure.	No. Fail-open. The LLM call continues.

Handling exceptions #

python

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

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

try:
    response = guard.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )
except BudgetExceededError as e:
    print(f"Budget exceeded: {e}")
except TokenLimitError as e:
    print(f"Token limit hit: {e}")
except CallLimitError as e:
    print(f"Call limit hit: {e}")
except RuntimeLimitError as e:
    print(f"Runtime limit hit: {e}")
except LoopDetectedError as e:
    print(f"Loop detected: {e}")

Catch the specific exception you care about. Each except branch reflects a distinct recovery path. Stop the agent, summarize context, or inject a new prompt.

ℹ️ Fail-open

Only the exceptions in the table propagate. If the backend is unreachable or returns an unexpected error, the SDK logs a warning and the LLM call proceeds.