Errors and troubleshooting

Treat an SDK failure as one of four different problems: invalid application input, unsupported capability, transient provider failure, or an uncertain side effect. The response should be different for each class.

Error map

Error	TypeScript	Python	Recommended response
Invalid SDK or model configuration	ConfigurationError	ConfigurationError	Fail deployment or startup; do not retry blindly.
Invalid input or contract	ValidationError	ValidationError	Return a reviewed client error or fix application code.
Provider cannot perform the requested feature	UnsupportedFeatureError	UnsupportedFeatureError	Select a compatible model/provider or remove the feature.
Provider HTTP failure	ProviderHTTPError	ProviderHTTPError	Retry only when the status or typed metadata says it is transient.
Tool timed out after a possible side effect	Application reconciliation	ToolExecutionOutcomeUnknown	Reconcile using the tool idempotency key before any retry.
Stored run was cancelled	Run status and cancellation APIs	AgentRunCancelled	Treat as terminal; do not overwrite the durable cancellation.
Application event delivery failed	Application observer handling	AgentEventDeliveryError	Inspect whether durable terminal state was already committed.

Do not expose raw provider bodies to clients. Log a redacted summary with request, tenant, provider, model, session, and run identifiers.

Retry only known transient failures

Provider adapters normalize HTTP failures into ProviderHTTPError where possible.

• TypeScript: inspect status and honor retryAfterMs. The built-in retry runtime treats 408, 429, and 5xx as retryable.
• Python: inspect the typed retryable flag and honor retry_after_ms; by default, 408, 429, and 5xx are transient.

Use a bounded endpoint timeout and a small retry budget. Authentication failures, validation failures, unsupported features, guardrail denials, and ordinary 4xx responses should not enter an automatic retry loop.

When TypeScript application code branches on concrete error classes, declare @zhivex-ai/core as a direct dependency and import the classes from that public entrypoint.

import { ProviderHTTPError } from "@zhivex-ai/core";

try {
  await callModel();
} catch (error) {
  if (error instanceof ProviderHTTPError) {
    const retryable = error.status === 408 || error.status === 429 || error.status >= 500;
    reportUpstreamFailure({
      status: error.status,
      retryable,
      retryAfterMs: error.retryAfterMs
    });
  }
  throw error;
}

from zhivex_ai import ProviderHTTPError

try:
    await call_model()
except ProviderHTTPError as error:
    report_upstream_failure(
        status=error.status,
        retryable=error.retryable,
        retry_after_ms=error.retry_after_ms,
    )
    raise

Retries do not make tool side effects safe. Pass a stable application idempotency key into retried work, and reconcile payments, email, deployments, and database writes before repeating them.

Common setup failures

Symptom	What to check
Package or module cannot be resolved	Use public entrypoints only. TypeScript requires Node >=18.18 or Bun >=1.3.7; Python requires >=3.11.
Python checkout import fails	Run make dev, then use .venv/bin/python; editable installation is the recommended checkout setup.
Optional Python import is missing	Install the matching extra: api, mcp, postgres, otel, or docx.
Provider returns 401 or 403	Verify the server-side credential, endpoint, project/deployment, and model access. Do not send provider keys from the browser.
Model works for text but fails for tools, media, or embeddings	Package availability is not capability parity. Recheck the provider guide.
Local HTTPS or realtime fails on macOS	For ssl.SSLCertVerificationError, refresh the certificate bundle used by that Python interpreter.
A smoke command skips a provider	A skip usually means its credentials or model ID are absent; it is not live-provider certification.

For Python provider setup, the usual environment variables are OPENAI_API_KEY, ANTHROPIC_API_KEY, AZURE_OPENAI_API_KEY plus AZURE_OPENAI_ENDPOINT, a Google API key or Vertex access token/project, DASHSCOPE_API_KEY or QWEN_API_KEY, and MOONSHOT_API_KEY or KIMI_API_KEY. vLLM requires the application to supply a compatible server URL and served model.

A practical diagnosis sequence

1. Reproduce the smallest failing call with one provider and model.
2. Record the exact error class, HTTP status, provider, model, operation, and request ID.
3. Confirm the requested capability in the provider guide.
4. Remove application middleware, gateway fallback, and tools one layer at a time.
5. Run offline checks before spending credentials on a live smoke.
6. When a tool may have produced an external side effect, stop and reconcile it before retrying.

Keep four evidence levels separate: an accepted model ID, an offline adapter test, an authenticated live operation, and a released application running the exact validated source. See production architecture for the surrounding identity, durability, and audit boundary.