Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vectorshift.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every SDK error subclasses VectorshiftError. API errors carry the HTTP status, the endpoint, and a parsed error message — enough to branch on and log cleanly. 
from vectorshift import (
    Pipeline,
    VectorshiftError,
    AuthenticationError,
    RateLimitError,
    PipelineRunFailedError,
)

try:
    result = Pipeline.fetch(name="my-pipeline").run({"q": "..."})
except AuthenticationError:
    ...  # missing or invalid key
except RateLimitError as e:
    ...  # back off; e.error_message contains the server hint
except PipelineRunFailedError as e:
    ...  # e.task_id, e.run_error
except VectorshiftError as e:
    ...  # fallback for any other SDK error

​
Hierarchy

VectorshiftError                    # base for every SDK error
├── VectorshiftApiError             # HTTP error from the API (alias: ApiStatusError)
│   ├── BadRequestError             # 400
│   ├── AuthenticationError         # 401
│   ├── PermissionDeniedError       # 403
│   ├── NotFoundError               # 404
│   ├── UnprocessableEntityError    # 422
│   ├── RateLimitError              # 429
│   ├── InternalServerError         # 500+
│   ├── PipelineRunFailedError      # run completed with failed status
│   └── PollTimeoutError            # polling exceeded the timeout
├── ApiConnectionError              # network-level failure
│   └── ApiTimeoutError             # request timed out before reaching the API
├── SessionError                    # base for session errors
│   └── SessionDisconnectedError    # websocket dropped
└── (KnowledgeBase ingestion errors)

​
Accessing objects you don’t own

The API key carries the org context. Every fetch / list / run / delete call is scoped to the org and user behind that key — there is no client-side ownership check because the only enforcement point that matters is the server. What you’ll see when you try to touch something outside your scope:
  • NotFoundError (404) — by design, the API returns 404 for both “doesn’t exist” and “exists but you can’t see it”. This prevents leaking object ids across orgs. Most cross-org accesses surface as 404.
  • PermissionDeniedError (403) — your key is valid but the specific operation isn’t allowed (e.g. you have read access to an object but try to delete it).
The same rules apply transitively. If a Pipeline you run references a sub-pipeline, KnowledgeBase, or Agent belonging to a different org, the engine will fail the run with a PipelineRunFailedError whose run_error points at the un-resolvable reference. 
from vectorshift import Pipeline, NotFoundError, PermissionDeniedError

try:
    other = Pipeline.fetch(id="<id-from-another-org>")
except NotFoundError:
    ...  # most likely outcome — by design, 404 hides existence
except PermissionDeniedError:
    ...  # less common — key valid for the resource type but not this op

​
Status code reference

StatusExceptionLikely causeFix
400BadRequestErrorMalformed request body (e.g. unsupported input_type)Check the call arguments against the reference.
401AuthenticationErrorVECTORSHIFT_API_KEY missing, expired, or revokedGenerate a new key at Account → API Keys.
403PermissionDeniedErrorKey valid, but lacks scope for the org or objectUse a key from the org that owns the object, or ask an admin to grant access.
404NotFoundErrorObject id / name doesn’t existVerify the id in the platform, or fetch by name= instead.
422UnprocessableEntityErrorServer rejected the payload semantically (e.g. invalid node wiring)e.error_message carries the server’s reason. Enabling the mypy plugin catches most of these at edit time.
429RateLimitErrorYou’re hitting rate limitsBack off and retry with jitter.
500+InternalServerErrorServer-side issueRetry once. If it persists, contact support.

​
Connection errors

ApiConnectionError covers anything that fails before getting an HTTP response — DNS, TLS, refused connections. Its subclass ApiTimeoutError is raised when the request times out. 
from vectorshift import ApiConnectionError, ApiTimeoutError

try:
    Pipeline.list()
except ApiTimeoutError:
    ...  # request never reached the API in time
except ApiConnectionError:
    ...  # network down, proxy issue, etc.

​
Pipeline-run errors

PipelineRunFailedError is raised when a run completes with a failed status. The exception carries the failing task_id and the server’s run_error string. 
from vectorshift import PipelineRunFailedError, PollTimeoutError

try:
    result = pipeline.run({"q": "..."}, timeout=30)
except PipelineRunFailedError as e:
    print(f"run {e.task_id} failed: {e.run_error}")
except PollTimeoutError as e:
    print(f"run {e.task_id} did not complete within {e.timeout}s")

​
Session errors

Conversational sessions communicate over a websocket. If the connection drops mid-stream, you get SessionDisconnectedError. Use the session as an async context manager — it cleans up on exit even when an error is raised. 
from vectorshift import SessionDisconnectedError

async with await agent.create_session() as session:
    await session.send("Hello")
    try:
        async for event in session.listen():
            ...
    except SessionDisconnectedError:
        ...  # reconnect or surface to the user

​
Anatomy of VectorshiftApiError

Every API error exposes these attributes:
​
status_code
int
HTTP status returned by the API.
​
method
str
HTTP method used ("GET", "POST", …).
​
endpoint
str
Path that was called, e.g. "/pipeline/<id>/run".
​
error_message
str
Best-effort parsed message from the response body — checks error, message, detail, errors in order.
​
raw_response
str
Original response body. Useful when error_message doesn’t surface what you need.
The default str(e) formats all of these together, plus a hint for common statuses. Log it directly — no need to build your own message.

​
What’s next

Authentication

Configure and rotate your API key.

Support

File an issue or reach the team.