Skip to main content

Errors

All SDK exceptions are importable from the top level, e.g. from cortexhub import ConfigurationError, APIError, CortexhubError.

CortexhubError​

The base class for every SDK exception. ConfigurationError, AuthenticationError, and APIError all subclass it, so catch CortexhubError to handle any SDK error in one place.

ConfigurationError​

Raised when Cortexhub() is constructed without a complete credential path: no agent API key and no full OAuth client id/secret pair.

from cortexhub import Cortexhub, ConfigurationError

Cortexhub()  # no CORTEXHUB_API_KEY and no CORTEXHUB_CLIENT_ID / CORTEXHUB_CLIENT_SECRET

Fix: pass api_key, or both client_id and client_secret, or set the matching environment variables.

AuthenticationError​

Raised when the MCP OAuth token endpoint returns 401 (invalid or revoked client credentials). OAuth path only; the agent-key path does no token exchange.

APIError​

Raised for a non-success HTTP response from an SDK HTTP call: the OAuth token endpoint, or session.decide(...) (the consent decision relay). The exception has a status attribute (for example 500; None for a connection-level failure).

Fix: for the OAuth path, verify client id/secret, that the client was created under Account → MCP API access, and CORTEXHUB_URL (default https://mcp.cortexhub.ai). For session.decide, check the approval_id is a pending approval this agent + end user owns.

MCP errors​

MCP JSON-RPC errors use CortexHub error codes documented in Outcomes. The SDK does not wrap these; your MCP client surfaces them. This applies to both credential paths, since the SDK only builds the URL and headers.