Error Handling

Error Handling

Both SDKs raise the same exception taxonomy. Every error carries the HTTP status, the engine's machine-readable error_code, and — in Python — the engine-assigned request_id; validation failures additionally expose per-field details.

The taxonomy

Exception	HTTP status	Raised when	Retried by default
AuthenticationError	401	Missing or invalid API key	No
NotFoundError	404	Resource does not exist	No
ValidationError	422	Request failed schema validation	No
RateLimitError	429	Quota or rate limit exceeded	Yes — honors the engine's Retry-After (retry_after / retryAfter, default 60s)
ServerError	5xx	Engine-side failure	Yes — exponential backoff
DecisionEngineError	any	Base class for all of the above	—

Transient network errors are retried on the same policy as 5xx responses. The Python SDK additionally never retries one rate-limit code, inline_preview_rate_limited.

Governance denials surface through this taxonomy too: a policy-blocked execute_decision comes back as the base DecisionEngineError with status_code == 409 and the gate (idempotency / confidence / risk_floor) named in error_code — see Governance Profiles & Receipts. Statuses without a dedicated subclass (any non-401/404/422/429/5xx failure) likewise raise the base class.

Retries and timeouts

Setting	Python	TypeScript	Default
Request timeout	timeout (seconds)	timeout (milliseconds)	120
Retries per request	max_retries	maxRetries	3

client = AlgentaClient(timeout=30.0, max_retries=5)                 # Python

const client = new AlgentaClient({ timeout: 30_000, maxRetries: 5 }); // TypeScript

Error attributes

Python (decision_engine.exceptions.DecisionEngineError):

Attribute	Meaning
status_code	HTTP status (0 for transport failures)
error_code	Engine's machine-readable code from the response body (unknown_error if absent)
request_id	Engine-assigned request ID — quote it in support reports
response_body	Raw decoded error body
details	Structured error.details payload, when present
field_errors	Per-field validation details (ValidationError)

TypeScript: statusCode, errorCode, fieldErrors, and retryAfter on RateLimitError (Python: retry_after).

Catch them

Python:

from decision_engine import (
    AlgentaClient,
    AuthenticationError,
    DecisionEngineError,
    NotFoundError,
    RateLimitError,
    ValidationError,
)

client = AlgentaClient()

try:
    result = client.query_with_metadata({"dataset_id": "ds_123", "metric": {"hint": "revenue"}})
except ValidationError as exc:
    for field_error in exc.field_errors:      # per-field schema violations
        print("invalid field:", field_error)
except RateLimitError as exc:
    print(f"retry after {exc.retry_after}s")  # already retried max_retries times
except NotFoundError:
    print("dataset does not exist")
except AuthenticationError:
    print("check ALGENTA_API_KEY")
except DecisionEngineError as exc:
    print(f"{exc.status_code} {exc.error_code} (request_id={exc.request_id})")

TypeScript:

import {
  AlgentaClient,
  AuthenticationError,
  DecisionEngineError,
  NotFoundError,
  RateLimitError,
  ValidationError,
} from "algenta-sdk";

const client = new AlgentaClient();

try {
  await client.queryWithMetadata({ dataset_id: "ds_123", metric: { hint: "revenue" } });
} catch (err) {
  if (err instanceof ValidationError) {
    console.error("invalid fields:", err.fieldErrors);
  } else if (err instanceof RateLimitError) {
    console.error(`retry after ${err.retryAfter}s`);
  } else if (err instanceof NotFoundError || err instanceof AuthenticationError) {
    console.error(err.message);
  } else if (err instanceof DecisionEngineError) {
    console.error(`${err.statusCode} ${err.errorCode}`);
  }
}

Client-side validation

Many failures never reach the network: blank identifiers, malformed filter specs, and out-of-range pagination raise ValueError / TypeError (Python) or Error (TS) before any HTTP call — e.g. get_audit_logs(actor_email=" ") fails locally. Treat those as programming errors, not retryable conditions.

Debugging checklist

1. Read error_code first — it is stable and machine-readable; message text is not a contract.
2. Grab request_id (Python) and quote it when filing an issue or contacting support.
3. On 401s: confirm which env var is set (ALGENTA_API_KEY, legacy DE_API_KEY) and that a self-hosted base_url uses an operator-provisioned key.
4. On unexpected connection failures in private profiles: ALGENTA_DEPLOYMENT_MODE=self_hosted / air_gapped fails closed on Algenta-owned hosts by design — see Getting Started → Hosted vs self-hosted.