Recoverable Runway SDK Client Pattern
Overview
A production client must separate request acceptance, provider task execution, and output persistence. The SDK removes protocol boilerplate, but the application still owns operation identity, deadlines, cancellation, state recovery, observability, and business decisions.
Prerequisites
- Pinned official Node or Python SDK and reviewed API contract
- Durable operation and provider-task persistence
- Injected timeout, retry, logging, and output-storage adapters
Instructions
Step 1: Create one client factory
Construct the SDK once per process from server-side configuration. Expose reviewed timeouts, retry policy, and user agent; do not scatter raw client creation across handlers.
Step 2: Define typed commands and results
Represent create intent, accepted task ID, provider state, terminal result, and stored asset separately. Prevent callers from treating an accepted create response as output.
Step 3: Persist before waiting
Write operation ID, normalized request hash, and provider task ID transactionally before calling a wait helper. On restart, retrieve the task and resume rather than creating again.
Step 4: Bound waiting
Use waitForTaskOutput or wait_for_task_output with a deadline and cancellation signal. A local abort or timeout stops waiting only; call the task cancellation endpoint when policy requires provider cancellation.
Step 5: Classify failures
Map HTTP responses, TaskFailedError, timeout, cancellation, and malformed output into distinct application errors. Retry only documented transient HTTP classes; never retry safety failures automatically.
Step 6: Store and observe
Copy output to owned storage, emit queue, run, and download timings, and record SDK version, API version, model, task ID, and redacted request fingerprint.
Authentication
The factory reads RUNWAYML_API_SECRET from a server secret provider. Direct protocol concerns such as bearer and version headers stay inside the SDK boundary; application logs must redact credentials and signed URLs.
Tool Discipline
Use Read and Grep to inspect application configuration, provider documentation, lockfiles, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, cancel, delete, retry, deploy, rotate, revoke, publish, or otherwise mutate production Runway resources without explicit operator approval.
Output
- Single typed client boundary with injected dependencies
- Restart-safe create, retrieve, wait, cancel, and output-copy behavior
- Structured error taxonomy and redacted telemetry contract
Return the environment, organization alias, operation and task identifiers, API and SDK versions, model or router policy, source-contract fingerprint, task-state evidence, credit boundary, output disposition, unresolved risk, rollback state, and final decision without exposing API secrets, prompt or media contents, or temporary signed URLs.
Examples
A web request submits a generation and disconnects. The worker has already saved the task ID, so another process retrieves it, waits with a new deadline, stores the output, and marks the operation complete without issuing a duplicate create.
Error Handling
| Failure | Response |
|---|---|
| SDK timeout | Return a nonterminal application state and schedule retrieval; cancel explicitly only when policy requires it. |
TaskFailedError with safety code | Record a redacted diagnostic and stop; do not convert it into a transport retry. |
| Malformed successful output | Quarantine the response, preserve task evidence, and avoid publishing an unvalidated URL. |
Validation
Run typed contract tests across every state and error class, kill the process after create to prove recovery, abort a wait to prove the provider task remains, and assert redaction of keys and URLs.