> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/api-and-integrations/sdk-getting-started/sdk-api-reference/exceptions.md).

# Exceptions

The exception hierarchy every call raises from.

## RootCauseError

Base class for every error this SDK raises.

## AuthenticationError

No usable credentials, or the platform rejected the ones provided.

## ConnectionFailedError

The platform could not be reached: DNS, TLS, refused connection, or a timeout.

## MalformedResponseError

The platform answered, but not with the shape this SDK needs.

## MissingDependencyError

An optional extra this call needs is not installed; the message names it.

## InvalidArgumentError

An argument could not be used as passed, caught before any request went out.

## RootCauseApiError

The API answered with a problem response.

| Attribute | Type  | Description                                        |
| --------- | ----- | -------------------------------------------------- |
| `status`  | `int` | HTTP status code.                                  |
| `title`   | `str` | Short problem title from the API.                  |
| `detail`  | `str` | The API's explanation, condensed to stay readable. |
| `body`    | `Any` | The raw problem body, when it was JSON.            |

### RootCauseApiError.from\_response

```python
RootCauseApiError.from_response(body: Any, status: int) -> RootCauseApiError
```

*Undocumented; the signature above is the contract.*

## JobFailedError

An asynchronous job finished in a terminal non-success state.

| Attribute | Type  | Description                     |
| --------- | ----- | ------------------------------- |
| `job_id`  | `str` | The job that failed.            |
| `status`  | `str` | The terminal state it ended in. |

## JobTimeoutError

An asynchronous job did not reach a terminal state within the allotted time.

The `timeout=` on the call that started it decides how long that is.

## NotFoundInWorkspaceError

A name or id did not resolve to exactly one object; carries suggestions.

| Attribute    | Type        | Description                                                  |
| ------------ | ----------- | ------------------------------------------------------------ |
| `kind`       | `str`       | What was being looked up, for example `workspace` or `twin`. |
| `needle`     | `str`       | The name or id that did not resolve.                         |
| `candidates` | `list[str]` | The closest names, as suggestions.                           |

## KindMismatchError

An explicit twin kind contradicts the panel/temporal kwargs supplied with it.

## AnchorSqlError

The Anchor SQL engine refused a statement; carries the structured compile error.

| Attribute         | Type                      | Description                                                                                                                                                                                                                                                                                        |
| ----------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`            | `str`                     | Machine-readable error code, for example `unknown_concept`, `parse_error` or `no_join_path`.                                                                                                                                                                                                       |
| `span`            | `tuple[int, int] \| None` | Character range of the offending fragment in the statement, when the engine could point at one.                                                                                                                                                                                                    |
| `candidates`      | `list[dict]`              | Near-miss suggestions, each with `kind`, `id`, `name` and `score`.                                                                                                                                                                                                                                 |
| `suggested_query` | `str \| None`             | A corrected statement the engine proposes.                                                                                                                                                                                                                                                         |
| `per_source`      | `list[dict]`              | Per-dataset diagnostics carried by errors that explain themselves dataset by dataset — `no_join_path` and `pin_no_edge` (why each side could not be joined) and `needs_enrichment` / `enrichment_running` (which datasets lack a geo sidecar) — each with `datasetId`, `datasetName` and `reason`. |
| `body`            | `dict`                    | The raw structured error.                                                                                                                                                                                                                                                                          |