> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mudraid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle errors

> How the SDK signals problems, and how to handle each one.

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:

```python theme={null}
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               |

```python theme={null}
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.

```python theme={null}
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.

## Related

* [Error responses (platform side)](/sdks/middleware/error-responses)
* [Debug with structured logs](/guides/agent-developer/debugging)