diff --git a/docs/source/designs/backup-recovery.yaml b/docs/source/designs/backup-recovery.yaml
index fd73f61c7eb9a0deb02d8e2e7959a95ad1c81878..77c291d4e635742b1edec3dc4001e836c7905c1d 100644
--- a/docs/source/designs/backup-recovery.yaml
+++ b/docs/source/designs/backup-recovery.yaml
@@ -1,36 +1,46 @@
 openapi: "3.1.0"
 info:
   title: "Backup / Recovery"
-  description: |
+  description: >-
     This API allows backup and recovery of ZKAPAuthorizer internal state.
   version: "1.0.0"
 paths:
   /storage-plugins/privatestorageio-zkapauthz-v1/recover:
     post:
-      description: |
+      description: >-
         Recover ZKAPAuthorizer state from a previously configured backup.
         This is only valid when ZKAPAuthorizer has no local state yet.
       requestBody:
         content:
           application/json:
             schema:
-              type: object
-              properties:
-                recovery-capability:
-                  type: "string"
-                  description: |
-                    The Tahoe-LAFS read-only capability for the recovery data.
-                    This is a capability previously returned by the backup
-                    endpoint.
+              $ref: "#/definitions/BackupConfiguration"
       responses:
-        200:
-          description: |
-            Recovery from the backup has been completed.
+        "500":
+          description: >-
+            Recovery from the backup has failed for some reason.
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/ErrorResponse"
+
+        "404":
+          description: >-
+            Recovery from the backup has failed because the recovery data
+            cannot be retrieved using the given capability.
+          content:
+            application/json:
+              schema:
+                $ref: "#/definitions/ErrorResponse"
+
+        "200":
+          description: >-
+            Recovery from the backup has succeeded.
           content:
             application/json:
               schema:
                 type: "object"
-                property: {}
+                properties: {}
 
   /storage-plugins/privatestorageio-zkapauthz-v1/backup:
     post:
@@ -46,14 +56,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  recovery-capability:
-                    type: "string"
-                    description: |
-                      The Tahoe-LAFS read-only capability for the recovery
-                      data.  This is the capability which can be submitted in
-                      order to initiate a recovery from the backup.
+                $ref: "#/definitions/BackupConfiguration"
 
         200:
           description: |
@@ -62,11 +65,24 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  recovery-capability:
-                    type: "string"
-                    description: |
-                      The Tahoe-LAFS read-only capability for the recovery
-                      data.  This is the capability which can be submitted in
-                      order to initiate a recovery from the backup.
+                $ref: "#/definitions/BackupConfiguration"
+
+definitions:
+  BackupConfiguration:
+    type: "object"
+    properties:
+      recovery-capability:
+        type: "string"
+        description: >-
+          The Tahoe-LAFS read-only capability for the recovery data.  This is
+          the capability which can be submitted in order to initiate a
+          recovery from the backup.
+
+  ErrorResponse:
+    type: "object"
+    properties:
+      details:
+        type: "string"
+        description: >-
+          A free-form text field which may give further details about the
+          failure.