@eigenpal/sdk 0.20.98 → 0.20.99

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @eigenpal/sdk
 
+## 0.20.99
+
+### Minor Changes
+
+- 996d1ef: Run responses expose structured errors with a machine-readable code, message,
+  retryability, and the configured business status code and step for workflow
+  rejections. Update consumers of the previous string error to read error.message.
+  HTTP success remains independent of the processing outcome.
+
 ## 0.20.91
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/sdk",
-  "version": "0.20.98",
+  "version": "0.20.99",
   "description": "Official TypeScript SDK for the EigenPal API",
   "type": "module",
   "main": "./src/index.ts",

package/src/generated/sdk.gen.ts

@@ -1020,7 +1020,7 @@ export const runsList = <ThrowOnError extends boolean = false>(options?: Options
  *
  * Start a run. Send JSON or multipart/form-data.
  *
- * How to read a run: the envelope is at the root. The automation business result is in `output` (per-automation, not this generic schema). Status is `execution.status` (`execution.retry.nextRun.status` is a later retry). `input`, `usage`, and `debug` appear only with `?expand=`. `eval` is present only on eval-scoped runs.
+ * How to read a run: the envelope is at the root. The automation business result is in `output` (per-automation, not this generic schema). HTTP 200 can report a failed run. Inspect `execution.status` and the structured `error` (`code`, `message`, `retryable`, and optional business `statusCode` and `step`). Status is `execution.status` (`execution.retry.nextRun.status` is a later retry). `input`, `usage`, and `debug` appear only with `?expand=`. `eval` is present only on eval-scoped runs.
  */
 export const runsStart = <ThrowOnError extends boolean = false>(options: Options<RunsStartData, ThrowOnError>): RequestResult<RunsStartResponses, RunsStartErrors, ThrowOnError> => (options.client ?? client).post<RunsStartResponses, RunsStartErrors, ThrowOnError>({
     security: [{ scheme: 'bearer', type: 'http' }],
@@ -1037,7 +1037,7 @@ export const runsStart = <ThrowOnError extends boolean = false>(options: Options
  *
  * Fetch one run by id. By default this returns core metadata plus terminal output/error fields. Pass `?expand=input,usage,execution,debug` to include detailed sub-objects; `expand=execution` is also where embedded review and expected artifacts appear.
  *
- * How to read a run: the envelope is at the root. The automation business result is in `output` (per-automation, not this generic schema). Status is `execution.status` (`execution.retry.nextRun.status` is a later retry). `input`, `usage`, and `debug` appear only with `?expand=`. `eval` is present only on eval-scoped runs.
+ * How to read a run: the envelope is at the root. The automation business result is in `output` (per-automation, not this generic schema). HTTP 200 can report a failed run. Inspect `execution.status` and the structured `error` (`code`, `message`, `retryable`, and optional business `statusCode` and `step`). Status is `execution.status` (`execution.retry.nextRun.status` is a later retry). `input`, `usage`, and `debug` appear only with `?expand=`. `eval` is present only on eval-scoped runs.
  */
 export const runsGet = <ThrowOnError extends boolean = false>(options: Options<RunsGetData, ThrowOnError>): RequestResult<RunsGetResponses, RunsGetErrors, ThrowOnError> => (options.client ?? client).get<RunsGetResponses, RunsGetErrors, ThrowOnError>({
     security: [{ scheme: 'bearer', type: 'http' }],

package/src/generated/types.gen.ts

@@ -1873,9 +1873,9 @@ export type RunListItem = {
      */
     eval?: RunEval;
     /**
-     * Terminal failure message. Present on terminal runs; null when the run succeeded. Absent while the run is still in flight.
+     * Structured processing failure, independent of the HTTP response status. Includes control.fail statusCode and step when known. Present on terminal runs; null when no error is recorded. Absent while in flight.
      */
-    error?: RunError;
+    error?: RunError | null;
     execution: RunExecutionMeta;
 };
 
@@ -1963,7 +1963,28 @@ export type RunEval = {
     passed: boolean | null;
 };
 
-export type RunError = string | null;
+export type RunError = {
+    /**
+     * Machine-readable failure code. Do not branch on message text.
+     */
+    code: string;
+    /**
+     * Human-readable failure explanation.
+     */
+    message: string;
+    /**
+     * HTTP-style business code configured by control.fail, not the API response status. Absent for untyped failures.
+     */
+    statusCode?: number;
+    /**
+     * Name of the control.fail step that rejected the run, when known.
+     */
+    step?: string;
+    /**
+     * Whether another attempt might succeed. Does not schedule a retry.
+     */
+    retryable: boolean;
+};
 
 export type RunExecutionMeta = {
     /**
@@ -2066,9 +2087,9 @@ export type Run = {
      */
     files?: Array<RunArtifact>;
     /**
-     * Terminal failure message. Present on terminal runs; null when the run succeeded. Absent while the run is still in flight.
+     * Structured processing failure, independent of the HTTP response status. Includes control.fail statusCode and step when known. Present on terminal runs; null when no error is recorded. Absent while in flight.
      */
-    error?: RunError;
+    error?: RunError | null;
     /**
      * Present only with `expand=input`.
      */
@@ -7583,6 +7604,10 @@ export type RunsStartErrors = {
      * Resource not found
      */
     404: ApiErrorEnvelope;
+    /**
+     * Organization deletion is in progress (organization_deleting), or an inline subworkflow target is unavailable (inline_invoke_target_unavailable). No run was started.
+     */
+    409: ApiErrorEnvelope;
     /**
      * Payload too large. Upload exceeded the per-request size cap.
      */
@@ -7605,7 +7630,7 @@ export type RunsStartError = RunsStartErrors[keyof RunsStartErrors];
 
 export type RunsStartResponses = {
     /**
-     * Run completed while waiting — same body as GET /api/v1/runs/:id
+     * Run reached a terminal status while waiting, including failure. Inspect execution.status. Same body as GET /api/v1/runs/:id
      */
     200: Run;
     /**
@@ -8013,6 +8038,10 @@ export type RunsRerunErrors = {
      * Missing or invalid API key
      */
     401: ApiErrorEnvelope;
+    /**
+     * Credit quota exceeded. The organization has spent its allowance; nothing was processed.
+     */
+    402: ApiErrorEnvelope;
     /**
      * API key lacks required scope
      */
@@ -8021,6 +8050,10 @@ export type RunsRerunErrors = {
      * Resource not found
      */
     404: ApiErrorEnvelope;
+    /**
+     * Conflict. The resource is in a state that forbids the request.
+     */
+    409: ApiErrorEnvelope;
     /**
      * Payload too large. Upload exceeded the per-request size cap.
      */
@@ -8043,7 +8076,7 @@ export type RunsRerunError = RunsRerunErrors[keyof RunsRerunErrors];
 
 export type RunsRerunResponses = {
     /**
-     * Rerun completed while waiting
+     * Rerun reached a terminal status while waiting, including failure. Inspect execution.status.
      */
     200: Run;
     /**

package/src/index.ts

@@ -88,6 +88,7 @@ export type {
   RunAccepted,
   RunArtifact,
   RunArtifactsResponse,
+  RunError,
   RunEvent,
   RunEventsResponse,
   RunListItem,

package/src/telemetry.ts

@@ -19,7 +19,7 @@
 export const SDK_LANGUAGE = 'typescript';
 // Rewritten at publish time by scripts/release/platform/render-sdk-versions.sh.
 // Keep this string literal exactly stable — sed matches on it.
-export const SDK_VERSION = '0.20.98';
+export const SDK_VERSION = '0.20.99';
 
 function detectRuntime(): string {
   const g = globalThis as unknown as {