MudraID — a trust layer for AI agents

The SDK draws a clear line between two kinds of failure:

Problems with authentication — bad credentials, a revoked agent, an unreachable MudraID. These the SDK raises as exceptions.
Responses from the platform you called — a 404, a 409, a 500 from the API itself. These come back as normal responses for your code to handle.

Understanding that line is the whole of error handling here.

Catch the base class for anything SDK-originated

Every exception the SDK raises inherits from MudraIDError. Catch the base class to handle all of them in one place:

from mudraid import Agent, MudraIDError

agent = Agent()
try:
    response = agent.get("https://api.skyscanner.com/flights")
except MudraIDError as exc:
    log.warning("MudraID rejected the call: %s", exc)

Catch a subclass when you want to react specifically

Exception	Raised when	Typical response
`MudraIDConfigError`	`MUDRAID_API_KEY_ID` or `MUDRAID_SECRET` is missing or empty	Fail fast at startup — it’s a misconfiguration
`MudraIDAuthError`	MudraID rejected the credentials (401)	Alert; the credentials are wrong or stale
`MudraIDRevokedError`	Access denied (403): agent inactive, no platform access, or scope rejected	Stop retrying; the agent needs attention in the portal
`MudraIDNetworkError`	MudraID was unreachable or returned something malformed	Retry with backoff — it may be transient
`MudraIDPlatformNotRegisteredError`	The URL’s host isn’t a platform this agent is registered with	Fix the target, or register the platform

from mudraid import MudraIDRevokedError, MudraIDNetworkError

try:
    response = agent.get(url)
except MudraIDRevokedError:
    alert_ops("agent lost access")      # don't retry
except MudraIDNetworkError:
    retry_later()                        # probably transient

Platform responses are not exceptions

A 4xx or 5xx from the platform itself is returned to you as an ordinary requests.Response. The SDK does not raise it — your code decides what a 404 or a 409 means for your application.

response = agent.get("https://api.example.com/items")
if response.status_code == 404:
    ...                       # your business logic, not an SDK error
response.raise_for_status()   # opt into requests' own error handling if you want

The one exception is a 401 from the platform: the SDK assumes the token expired, refreshes it, and retries once before handing the response back. So you rarely see a 401 at all.