Errors and retries

Import SDK exceptions from thinkplatform.sdk. If the CLI succeeds but Python or a managed workspace fails, use the shared troubleshooting workflow. The API reference and models reference 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. It avoids printing tokens or response bodies.

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.

Get started

CLI

Python SDK

Agent skills

Handle a read failure

Retry behavior

​Handle a read failure

​Retry behavior

Handle a read failure

Retry behavior