diff --git a/README.md b/README.md
index 7ee47bf..ed243f7 100644
--- a/README.md
+++ b/README.md
@@ -254,6 +254,31 @@ When the `waitForActionAttempt` option is enabled, the SDK:
 - Rejects with a `SeamActionAttemptTimeoutError` if the action attempt is still pending when the `timeout` is reached.
 - Both errors expose an `actionAttempt` property.
 
+The `ActionAttempt` type is a union discriminated by `action_type` and `status`.
+The `error` and `result` properties are typed as `null`
+except for the status that populates them,
+so narrow on the `status` before reading them:
+
+```ts
+const actionAttempt = await seam.locks.unlockDoor(
+  { device_id },
+  { waitForActionAttempt: false },
+)
+
+if (actionAttempt.status === 'success') {
+  console.log(actionAttempt.result) // The result is non-null here.
+}
+
+if (actionAttempt.status === 'error') {
+  console.log(actionAttempt.error.message) // The error is non-null here.
+}
+```
+
+Waiting for an action attempt resolves with the successful action attempt,
+so after checking `status === 'success'` the `result` is immediately usable.
+Use the `SucceededActionAttempt` and `FailedActionAttempt` types
+to extract the success and error members from any action attempt type.
+
 If you already have an action attempt ID
 and want to wait for it to resolve, simply use
 
diff --git a/package-lock.json b/package-lock.json
index 5b54264..89f8833 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10,7 +10,7 @@
       "license": "MIT",
       "dependencies": {
         "@seamapi/cli": "0.37.0",
-        "@seamapi/http": "2.26.0",
+        "@seamapi/http": "2.27.0",
         "@seamapi/webhook": "1.5.0"
       },
       "bin": {
@@ -3378,9 +3378,9 @@
       }
     },
     "node_modules/@seamapi/http": {
-      "version": "2.26.0",
-      "resolved": "https://registry.npmjs.org/@seamapi/http/-/http-2.26.0.tgz",
-      "integrity": "sha512-wxsTQVYUZJSq4r6ezodyvt9QF7slfSMHGPP3HEqazfhynZEu1yPdMPR+9+foKGdCGHlJl1+bDNmV1lqdT5agYw==",
+      "version": "2.27.0",
+      "resolved": "https://registry.npmjs.org/@seamapi/http/-/http-2.27.0.tgz",
+      "integrity": "sha512-Rnp/hopA/UhdiWMFAqlvJ3ZmhUqBpBVRgmxYM8T3p/MIkS8WxjEYOrYb6/ZE+CgyKNZjcHyRtwTebNYpXI+XGw==",
       "license": "MIT",
       "dependencies": {
         "@seamapi/url-search-params-serializer": "^3.0.3",
diff --git a/package.json b/package.json
index a80e432..802e2ef 100644
--- a/package.json
+++ b/package.json
@@ -76,7 +76,7 @@
   "packageManager": "npm@11.19.0",
   "dependencies": {
     "@seamapi/cli": "0.37.0",
-    "@seamapi/http": "2.26.0",
+    "@seamapi/http": "2.27.0",
     "@seamapi/webhook": "1.5.0"
   },
   "devDependencies": {