> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended**:
> ```bash
> npx @scalekit-inc/cli setup
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for 40+ agents.
> Features: full-stack-auth, agent-auth, mcp-auth, modular-sso, modular-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Error handling

Catch Scalekit exceptions from AgentKit calls and handle not-found, auth, and server failures
AgentKit methods throw typed exceptions when the API returns an error. Catch the specific type first, then fall back to the base server exception.

## Catch exceptions

```python wrap showLineNumbers=false
from scalekit.common.exceptions import (
    ScalekitNotFoundException,
    ScalekitUnauthorizedException,
    ScalekitForbiddenException,
    ScalekitServerException,
)

try:
    account = scalekit_client.actions.get_connected_account(
        connection_name="gmail",
        identifier="user@example.com",
    )
except ScalekitNotFoundException:
    # No connected account yet — create one or send the user through OAuth
    pass
except ScalekitUnauthorizedException:
    # Invalid or expired client credentials / tokens
    pass
except ScalekitForbiddenException:
    # Caller is authenticated but not allowed for this resource
    pass
except ScalekitServerException as e:
    # Unexpected API or platform error
    print(e.error_code, e.http_status)
```

## Exception types

| Exception | When it is raised | Typical response |
| --- | --- | --- |
| `ScalekitNotFoundException` | Resource does not exist (connected account, tool, config) | Create the resource or return a clear not-found to the user |
| `ScalekitUnauthorizedException` | Missing or invalid credentials | Refresh tokens or fix client ID/secret |
| `ScalekitForbiddenException` | Authenticated but not permitted | Adjust scopes, org, or role |
| `ScalekitServerException` | Base class for Scalekit HTTP/API failures | Log, retry when safe, surface a generic error |

`ScalekitServerException` is the base type. Prefer checking subclasses first so not-found and auth failures get the right UX.

## Related

- [Connected accounts](/agentkit/sdks/python/actions/) — connect accounts and execute tools  
- [Tool calling](/agentkit/sdks/python/tools/) — list tool definitions  
- [Install](/agentkit/sdks/python/) — create the Scalekit client


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |