Error Handling

All SDK exceptions inherit from ProximaError.

from proxima_sdk.exceptions import (
    ProximaError,
    KnowledgeError,
    AuthenticationError,
    RateLimitError,
    ToolExecutionError,
)

Exception types

Exception	When raised
`KnowledgeError`	Knowledge query failed (source unavailable, timeout)
`AuthenticationError`	Platform rejected the request (invalid token, expired session)
`RateLimitError`	Too many requests — includes `retry_after` attribute
`ToolExecutionError`	Unhandled exception inside a tool function

Example

from proxima_sdk.exceptions import KnowledgeError, RateLimitError
import time

def my_tool(params: dict, ctx: PlatformContext) -> dict:
    try:
        results = ctx.knowledge.query(params["question"])
        return {"answer": results.answer}
    except RateLimitError as e:
        time.sleep(e.retry_after)
        results = ctx.knowledge.query(params["question"])
        return {"answer": results.answer}
    except KnowledgeError as e:
        ctx.governance.log_action("knowledge_error", metadata={"error": str(e)})
        return {"error": "Knowledge base unavailable. Please try again."}

⚠

Always handle KnowledgeError gracefully. Agents should degrade gracefully when a data source is temporarily unavailable rather than surfacing raw exceptions to users.