- Standardize Python SDK (`datastack`) documentation with a new multi-file suite. - Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package. - Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
4.1 KiB
4.1 KiB
Error Handling & Exception Reference
The DataStack Python SDK implements a structured exception hierarchy distinguishing between fatal configuration/auth errors and transient, auto-recoverable issues.
1. Exception Hierarchy
All exceptions inherit from DataStackError:
DataStackError (Base)
├── DataStackConfigError (Configuration missing, malformed, or CLIENT_ID mismatch)
├── DataStackAuthError (Token rejected, client revoked, or rotated)
├── DataStackConnectionError (Network unreachable, endpoints down, offline)
├── DataStackRateLimitError (Rate limit exceeded after all retry attempts)
├── DataStackPayloadTooLargeError (Payload exceeds maximum permitted size)
├── DataStackFileError (File missing, unsupported extension, or corrupted)
└── DataStackOfflineSpoolError (Disk spool directory unwriteable or disk quota full)
2. Exceptions Specification
DataStackConfigError
- Raised When:
CLIENT_TOKENis missing or contains placeholder strings.- An explicit
CLIENT_IDdoes not match the subject claim insideCLIENT_TOKEN. config.datastack.pycontains invalid Python syntax.
- Retryable: No. Requires modifying configuration files or environment variables.
DataStackAuthError
- Raised When:
- The server returns HTTP
401 Unauthorizedor403 Forbidden. - The WebSocket handshake is rejected with
AUTH_REQUIRED,AUTH_INVALID,CLIENT_REVOKED, orTOKEN_ROTATED.
- The server returns HTTP
- Special Behavior: Immediately stops the background Heartbeat Monitor thread to prevent hammering the server with invalid credentials.
- Retryable: No. The operator must update the client token or re-activate the client in
/vcon/clients.
DataStackRateLimitError
- Raised When:
- The client exceeds its allocated events-per-second quota (
429 RATE_LIMIT_EXCEEDED).
- The client exceeds its allocated events-per-second quota (
- Retryable: Yes. The SDK automatically executes exponential backoff retries with jitter and a minimum 1.05-second pause to allow the 1-second server sliding window to reset. This exception is only raised if all configured retries (
MAX_RETRIES) are exhausted.
DataStackPayloadTooLargeError
- Raised When:
- A single event payload exceeds
maxPayloadSizeKb(HTTP413 PAYLOAD_TOO_LARGE).
- A single event payload exceeds
- Special Handling in Batches: When calling
send_batch(), the SDK catches this error and automatically divides the batch in half (chunk // 2) recursively, retrying each sub-chunk transparently.
DataStackConnectionError
- Raised When:
- Both the primary WebSocket (
Port 4000) and the HTTP fallback API (Port 3000) are unreachable, AND offline disk spooling is disabled (OFFLINE_SPOOL_ENABLED=False).
- Both the primary WebSocket (
- Retryable: Yes.
DataStackFileError
- Raised When:
- A file path passed to
send_file()does not exist or is a directory. - The file extension is unsupported (only
.csv,.json,.jsonl,.ndjsonallowed). - A JSONL file contains corrupted or unparseable JSON on a specific line number.
- A file path passed to
DataStackOfflineSpoolError
- Raised When:
- The
.datastack_spool/directory cannot be created due to permission errors. - The spool file size exceeds
MAX_SPOOL_SIZE_MB(default: 50 MB).
- The
3. Recommended Error Handling Pattern
from datastack import (
DataStack,
DataStackAuthError,
DataStackConfigError,
DataStackConnectionError,
DataStackRateLimitError,
DataStackError,
)
try:
client = DataStack()
client.send({"temperature": 23.4})
except DataStackConfigError as exc:
print(f"Configuration defect: {exc}")
except DataStackAuthError as exc:
# Token expired, revoked, or rotated
print(f"Authentication failure: {exc.code} - {exc.message}")
# Alert operations team to rotate or update CLIENT_TOKEN
except DataStackRateLimitError as exc:
print(f"Rate limit exceeded after retries: {exc}")
except DataStackConnectionError as exc:
print(f"Network unreachable and spooling disabled: {exc}")
except DataStackError as exc:
print(f"Unexpected DataStack error: {exc}")