diff --git a/packages/api/src/generated/contracts.ts b/packages/api/src/generated/contracts.ts
index a7904a4b78..d694679387 100644
--- a/packages/api/src/generated/contracts.ts
+++ b/packages/api/src/generated/contracts.ts
@@ -2661,7 +2661,11 @@ export const V1GetPgsodiumConfigInput = Schema.Struct({
     .check(Schema.isMaxLength(20))
     .check(Schema.isPattern(new RegExp("^[a-z]+$"))),
 });
-export const V1GetPgsodiumConfigOutput = Schema.Struct({ root_key: Schema.String });
+export const V1GetPgsodiumConfigOutput = Schema.Struct({
+  root_key: Schema.String.annotate({
+    description: "The pgsodium root key: 32 bytes, hex-encoded (64 characters).",
+  }),
+});
 export const V1GetPoolerConfigInput = Schema.Struct({
   ref: Schema.String.check(Schema.isMinLength(20))
     .check(Schema.isMaxLength(20))
@@ -5611,9 +5615,15 @@ export const V1UpdatePgsodiumConfigInput = Schema.Struct({
   ref: Schema.String.check(Schema.isMinLength(20))
     .check(Schema.isMaxLength(20))
     .check(Schema.isPattern(new RegExp("^[a-z]+$"))),
-  root_key: Schema.String,
+  root_key: Schema.String.annotate({
+    description: "The pgsodium root key: 32 bytes, hex-encoded (64 characters).",
+  }),
+});
+export const V1UpdatePgsodiumConfigOutput = Schema.Struct({
+  root_key: Schema.String.annotate({
+    description: "The pgsodium root key: 32 bytes, hex-encoded (64 characters).",
+  }),
 });
-export const V1UpdatePgsodiumConfigOutput = Schema.Struct({ root_key: Schema.String });
 export const V1UpdatePoolerConfigInput = Schema.Struct({
   ref: Schema.String.check(Schema.isMinLength(20))
     .check(Schema.isMaxLength(20))
diff --git a/packages/api/src/generated/openapi.json b/packages/api/src/generated/openapi.json
index 1def222168..3ae234fd03 100644
--- a/packages/api/src/generated/openapi.json
+++ b/packages/api/src/generated/openapi.json
@@ -4273,7 +4273,14 @@
             }
           },
           "400": {
-            "description": "This feature requires the Pro, Team, or Enterprise organization plan."
+            "description": "This feature requires the Pro, Team, or Enterprise organization plan.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanGateErrorBody"
+                }
+              }
+            }
           },
           "401": {
             "description": "Unauthorized"
@@ -4406,7 +4413,14 @@
             }
           },
           "400": {
-            "description": "This feature requires the Pro, Team, or Enterprise organization plan."
+            "description": "This feature requires the Pro, Team, or Enterprise organization plan.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanGateErrorBody"
+                }
+              }
+            }
           },
           "401": {
             "description": "Unauthorized"
@@ -4486,7 +4500,14 @@
             }
           },
           "400": {
-            "description": "This feature requires the Pro, Team, or Enterprise organization plan."
+            "description": "This feature requires the Pro, Team, or Enterprise organization plan.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanGateErrorBody"
+                }
+              }
+            }
           },
           "401": {
             "description": "Unauthorized"
@@ -4884,7 +4905,14 @@
             "description": "Unauthorized"
           },
           "402": {
-            "description": "This feature requires the Pro, Team, or Enterprise organization plan."
+            "description": "This feature requires the Pro, Team, or Enterprise organization plan.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanGateErrorBody"
+                }
+              }
+            }
           },
           "403": {
             "description": "Forbidden action"
@@ -10897,7 +10925,14 @@
             "description": "Unauthorized"
           },
           "402": {
-            "description": "This feature requires the Enterprise organization plan."
+            "description": "This feature requires the Enterprise organization plan.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanGateErrorBody"
+                }
+              }
+            }
           },
           "403": {
             "description": "Forbidden action"
@@ -10982,7 +11017,14 @@
             "description": "Unauthorized"
           },
           "402": {
-            "description": "This feature requires the Enterprise organization plan."
+            "description": "This feature requires the Enterprise organization plan.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlanGateErrorBody"
+                }
+              }
+            }
           },
           "403": {
             "description": "Forbidden action"
@@ -13371,21 +13413,26 @@
         "type": "object",
         "properties": {
           "root_key": {
-            "type": "string"
+            "type": "string",
+            "description": "The pgsodium root key: 32 bytes, hex-encoded (64 characters)."
           }
         },
-        "required": ["root_key"]
+        "required": ["root_key"],
+        "example": {
+          "root_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+        }
       },
       "UpdatePgsodiumConfigBody": {
         "type": "object",
         "properties": {
           "root_key": {
-            "type": "string"
+            "type": "string",
+            "description": "The pgsodium root key: 32 bytes, hex-encoded (64 characters)."
           }
         },
         "required": ["root_key"],
         "example": {
-          "root_key": "MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY="
+          "root_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
         }
       },
       "PostgrestConfigWithJWTSecretResponse": {
@@ -13626,6 +13673,36 @@
         },
         "required": ["status"]
       },
+      "PlanGateErrorBody": {
+        "type": "object",
+        "properties": {
+          "message": {
+            "type": "string",
+            "description": "Human-readable explanation of the plan gate"
+          },
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": ["entitlement_required"],
+                "description": "Machine-readable marker for plan-gated denials"
+              },
+              "feature": {
+                "type": "string",
+                "description": "Entitlement feature key that failed the check"
+              },
+              "upgrade_url": {
+                "type": "string",
+                "description": "Billing page URL for the organization, present when the org is resolvable"
+              }
+            },
+            "required": ["code", "feature"],
+            "description": "Present on entitlement denials. Other errors with this status code (validation, billing state) carry only message."
+          }
+        },
+        "required": ["message"]
+      },
       "VanitySubdomainBody": {
         "type": "object",
         "properties": {