Sandbox errors and retries

Sandbox operations can change live external state. Retry decisions must account for whether a mutation was definitely rejected, definitely completed, or may have happened without a confirmed response.

REST error responses

REST errors use an errors array:

{
  "errors": [
    {
      "code": "operation_ambiguous",
      "message": "Sandbox process operation may have executed and must not be retried automatically"
    }
  ]
}

Use code for control flow. Messages are written for humans and can change.

SDK errors

The TypeScript SDK converts API and transport failures to SandboxError:

class SandboxError extends Error {
  action: SandboxAction;
  code: SandboxErrorCode;
  status?: number;
  sandboxId?: string;
  processId?: string;
  ambiguous: boolean;
  retryable: boolean;
  requestId?: string;
  details: readonly Record<string, unknown>[];
  cause?: unknown;
}

Invalid local input and malformed server responses throw SandboxValidationError.

The direct client never retries automatically, even when retryable is true.

Inside step.sandbox:

• SandboxError with retryable: true becomes a retriable step error;
• non-retryable SandboxError becomes NonRetriableError; and
• SandboxValidationError becomes NonRetriableError.

This uses the function's ordinary step retry behavior. It does not provide exactly-once dispatch.

Error reference

sandbox_exec_output_too_large, sandbox_exec_timed_out, and operation_ambiguous all produce SandboxError.ambiguous === true and retryable === false.

Reads and mutations

Safe reads do not modify sandbox state:

• List and Get sandbox;
• List, Get, and Wait process;
• retained process output;
• sandbox and process streams; and
• file download.

Mutations can have external effects:

• Create sandbox;
• captured Exec;
• Destroy sandbox;
• Start process;
• Signal process; and
• file upload.

Retry safe reads

For 429 rate_limited and 503 compute_unavailable, retry a direct read with bounded exponential backoff and jitter:

This example is for the direct inngest.sandboxes client. Do not add this loop around step.sandbox; Inngest already retries its retryable step errors.

import { SandboxError } from "inngest/experimental";

const sleep = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));

async function getSandboxWithBackoff(id: string) {
  for (let attempt = 0; attempt < 4; attempt++) {
    try {
      return await inngest.sandboxes.get(id);
    } catch (error) {
      if (!(error instanceof SandboxError) || !error.retryable) {
        throw error;
      }

      const delay = Math.min(250 * 2 ** attempt, 2_000);
      await sleep(delay + Math.floor(Math.random() * 100));
    }
  }

  throw new Error("Sandbox is still unavailable");
}

The direct client does not reconnect streams. A manual reconnect can replay retained chunks, so consumers must tolerate duplicates.

Retry mutations only before dispatch

A mutation can retry only when the service confirms that it failed before dispatch. Examples include a 429 rate-limit response or a 503 response produced before a node session was obtained.

Do not infer safety from a missing HTTP response. The direct SDK conservatively maps a transport failure during a mutation to operation_ambiguous.

Handle ambiguous operations

Ambiguity means the platform cannot prove whether the mutation happened:

Do not catch an ambiguous error just to log it or call the operation again. Inside an Inngest function, let the error escape; it is non-retryable. With the direct client, let it escape unless you are implementing an explicit reconciliation or operator-review path.

Possible reconciliation strategies:

• Create: list sandboxes and inspect the intended unique name.
• Destroy: get and inspect TERMINATING or terminal state.
• Start: list processes if the UUID is known. Direct Start does not expose its generated UUID before dispatch, so strong reconciliation is not always possible.
• Signal: get or wait, remembering that not every signal terminates a process.
• File upload: download or inspect the destination.
• Captured Exec: design the command to be idempotent or write a completion marker.

Reconciliation is application policy. The SDK does not guess.

Understand step.sandbox replay

step.sandbox uses ordinary step.run memoization:

1. The step handler sends the REST request.
2. The SDK converts the response to JSON-safe data.
3. Inngest persists the result.
4. Replay reconstructs the Sandbox object from that result.

If a REST mutation commits and the function process stops before the result is persisted, Inngest can run the handler again. There is no sandbox-specific executor fence and no HTTP Idempotency-Key.

An observed operation_ambiguous is non-retriable. A process crash cannot report that error, so mutation commands should tolerate the ordinary at-least-once step window.

Validation and size limits

Sandbox

Entitlements or capacity can impose lower effective resource limits.

Commands and process Start

Additional rules:

• command[0] must be absolute;
• arguments, keys, values, and cwd cannot contain NUL;
• environment keys must be non-empty and cannot contain =;
• the SDK rejects invalid Unicode surrogate sequences; and
• environment replaces rather than merges with the guest environment.

Captured Exec

The middleware applies the 2 MiB durable limit after a successful REST response. Larger results succeed with deterministic tail truncation and report original and retained byte counts.

Managed processes

There is no process runtime timeout. Stop a process with a signal.

Files

Stream errors after HTTP 200

An NDJSON stream can fail after response headers are committed. The API sends a terminal frame:

{
  "type": "error",
  "errors": [
    {
      "code": "compute_unavailable",
      "message": "Compute is temporarily unavailable"
    }
  ]
}

Treat the frame as a failed stream. The TypeScript SDK turns it into SandboxError.

A binary file download cannot append a JSON frame after HTTP 200. Verify that the body length matches Content-Length; a short body is a failed download.