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

> ## Agent Instructions
> Choose User guide for browser tasks, Developers for CLI, SDK and external agents, and Administration for organization management.
> Confirm identity and organization/project context before operations. Documentation access does not grant ThinkPlatform permissions.
> Review side effects, verify changes with a read, and do not blindly retry an operation with an uncertain outcome.
> Use documented UI steps for the web app and documented public CLI or SDK interfaces for automation. Follow each page’s prerequisites and authentication requirements.

# Errors and retries

> Handle missing context, credential failures, connection problems, and API errors.

Import SDK exceptions from `thinkplatform.sdk`.

If the CLI succeeds but Python or a managed workspace fails, use the shared [troubleshooting workflow](https://docs.thinkplatform.ai/cli/guides/troubleshooting.md). The [API reference](https://docs.thinkplatform.ai/python-sdk/api-reference.md) and [models reference](https://docs.thinkplatform.ai/python-sdk/models.md) document resource-specific inputs and results.

| Exception | What it means | Next step |
| - | - | - |
| `MissingContextError` | Required organization/project context is missing, or a request URL is invalid, ambiguous, or outside the configured API origin. Restricted execution requests also reject absolute paths. Subclasses `ValueError`. | Correct the context or URL before retrying. |
| `TokenAcquisitionError` | Credential configuration, acquisition, exchange, expiry, or execution-context validation failed. Subclasses `RuntimeError`. | Correct the credential setup or obtain a new authorized credential. |
| `ThinkPlatformApiError` | API returned HTTP 400 or higher, or the API transport raised an `httpx.HTTPError`. Subclasses `RuntimeError`. | Inspect `status_code`; it is `None` for wrapped transport failures. |
| `ValueError` / Pydantic validation errors | An endpoint returned an unexpected shape or model validation failed; some invalid input is also rejected locally. | Check the input and confirm that your SDK version is compatible with the server. |

`ThinkPlatformApiError.response_body` contains the parsed error response when available. It can include sensitive information; do not log it indiscriminately. An HTTP error's message is derived from `message`, `detail`, or `error`, or the HTTP reason. Wrapped transport errors preserve the original `httpx` exception as `__cause__`; SDK API calls do not expose an `httpx.HTTPStatusError` for an unsuccessful status.

## Handle a read failure

This example uses the explicit bearer-token and context environment settings from [resource workflows](https://docs.thinkplatform.ai/python-sdk/resources.md). It avoids printing tokens or response bodies.

```python theme={"system"}
import os
from thinkplatform.sdk import (
    MissingContextError,
    StaticTokenCredential,
    ThinkPlatformApiError,
    ThinkPlatformClient,
    TokenAcquisitionError,
)

try:
    with ThinkPlatformClient(
        base_url=os.environ["THINKPLATFORM_API_BASE_URL"],
        credential=StaticTokenCredential(os.environ["THINKPLATFORM_ACCESS_TOKEN"]),
        org_id=int(os.environ["THINKPLATFORM_ORG_ID"]),
        project_id=int(os.environ["THINKPLATFORM_PROJECT_ID"]),
    ) as client:
        print(len(client.home.pages.list()))
except MissingContextError:
    print("Set the required organization and project context.")
except TokenAcquisitionError:
    print("Check the credential configuration.")
except ThinkPlatformApiError as exc:
    if exc.status_code is None:
        print("The API could not be reached.")
    else:
        print(f"API request failed with HTTP {exc.status_code}.")
```

## Retry behavior

For normal API requests, the SDK reacts to HTTP **401** by invalidating the credential cache, requesting a token with `force_refresh=True`, and sending the request once more. A second failure is raised. Static tokens are unchanged by refresh. This retry can replay a write request too.

The SDK does not automatically retry transport failures, HTTP 429, or HTTP 5xx responses in this request path. Design any application retry policy around the operation's safety. A timeout after a write does not prove the server rejected it; read the resource state before repeating a mutation. Handle authorization failures by checking permissions and context rather than repeatedly retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.