pipecat-ai · markbackman · May 7, 2026 · May 7, 2026
diff --git a/api-reference/cli/cloud/deploy.mdx b/api-reference/cli/cloud/deploy.mdx
@@ -40,7 +40,9 @@ pipecat cloud deploy [ARGS] [OPTIONS]
 <ParamField path="--credentials / -c" type="string">
   Name of the image pull secret to use for accessing private repositories. The
   secret must be previously created using the `pipecat cloud secrets
-  image-pull-secret` command.
+  image-pull-secret` command, and must be in the
+  [`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+  state at deploy time.
 </ParamField>
 
 <ParamField path="--organization / -o" type="string">
@@ -50,7 +52,9 @@ pipecat cloud deploy [ARGS] [OPTIONS]
 
 <ParamField path="--secrets / -s" type="string">
   Name of the secret set to use for the deployment. The secret set must exist in
-  the specified organization.
+  the specified organization and must be in the
+  [`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+  state — deploys that bind a `pending` or `failed` set are rejected.
 </ParamField>
 
 <ParamField path="--min-agents / -min" type="number" default="0">
@@ -284,7 +288,9 @@ region = "us-east"
 
 <ParamField path="secret_set" type="string">
 Name of the secret set to use for environment variables. The secret set must
-exist in the same region as the agent.
+exist in the same region as the agent and must be in the
+[`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+state — deploys that bind a `pending` or `failed` set are rejected.
 
 ```toml
 secret_set = "my-agent-secrets"
@@ -293,7 +299,7 @@ secret_set = "my-agent-secrets"
 </ParamField>
 
 <ParamField path="image_credentials" type="string">
-Name of the image pull secret for private registries. The image pull secret must exist in the same region as the agent.
+Name of the image pull secret for private registries. The image pull secret must exist in the same region as the agent and must be in the [`ready`](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness) state.
 
 ```toml
 image_credentials = "dockerhub-credentials"

diff --git a/api-reference/cli/cloud/secrets.mdx b/api-reference/cli/cloud/secrets.mdx
@@ -8,8 +8,12 @@ The `secrets` command group helps you manage sensitive information for your agen
 ## list
 
 List secret sets and image pull secrets for active namespace / organization.
+Each row includes a
+[readiness status](/pipecat-cloud/fundamentals/secrets#provisioning-and-readiness)
+(`ready`, `pending`, or `failed`).
 
-If provided with a valid secret set name, will show the keys of that set (values are hidden.)
+If provided with a valid secret set name, will show the keys of that set
+alongside its status (values are hidden).
 
 **Usage:**
 

diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-secret-create-update.json b/api-reference/pipecat-cloud/rest-reference/openapi-secret-create-update.json
@@ -15,7 +15,7 @@
     "/secrets/{setName}": {
       "put": {
         "summary": "Create or update a secret set",
-        "description": "Create a new secret set or update an existing one. Supports both regular secrets (multiple key-value pairs) and image pull secrets.",
+        "description": "Create a new secret set or update an existing one. Supports both regular secrets (multiple key-value pairs) and image pull secrets.\n\nProvisioning is **asynchronous**: the response is `202 Accepted` once the values have been stored, and the secret set is then provisioned into the target region in the background. Use `GET /secrets/{setName}` to observe the readiness status (`pending` → `ready`). Deploys that bind a secret set whose status is not `ready` are rejected with `409 Conflict`.",
         "operationId": "upsertSecretSet",
         "security": [
           {
@@ -83,8 +83,8 @@
           }
         },
         "responses": {
-          "200": {
-            "description": "Secret set successfully created or updated",
+          "202": {
+            "description": "Secret set accepted. Values have been stored and the set is being provisioned into the target region in the background. Poll `GET /secrets/{setName}` until `status` is `ready` before binding it to a deploy.",
             "content": {
               "application/json": {
                 "schema": {
@@ -169,6 +169,20 @@
               }
             }
           },
+          "409": {
+            "description": "Conflict - Another request is modifying this secret set concurrently. Retry the request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Secret set 'my-secrets' was modified concurrently. Please retry.",
+                  "code": "CONFLICT"
+                }
+              }
+            }
+          },
           "500": {
             "description": "Internal server error",
             "content": {

diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-all.json b/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-all.json
@@ -43,12 +43,14 @@
                     {
                       "name": "my-app-secrets",
                       "type": "secret",
-                      "region": "us-west"
+                      "region": "us-west",
+                      "status": "ready"
                     },
                     {
                       "name": "dockerhub-credentials",
                       "type": "imagePullSecret",
-                      "region": "us-west"
+                      "region": "us-west",
+                      "status": "pending"
                     }
                   ]
                 }
@@ -120,6 +122,15 @@
           "region": {
             "type": "string",
             "description": "The region where the secret set is stored"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "ready", "failed"],
+            "description": "Readiness state. `pending` while provisioning is in flight, `ready` once the set can be bound to a deploy, `failed` if provisioning could not complete."
+          },
+          "errorMessage": {
+            "type": "string",
+            "description": "Customer-facing message returned only when `status` is `failed`."
           }
         }
       }

diff --git a/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-one.json b/api-reference/pipecat-cloud/rest-reference/openapi-secret-list-one.json
@@ -38,7 +38,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Secret set details",
+            "description": "Secret set details, including readiness status",
             "content": {
               "application/json": {
                 "schema": {
@@ -48,6 +48,15 @@
                       "type": "string",
                       "description": "The region where the secret set is stored"
                     },
+                    "status": {
+                      "type": "string",
+                      "enum": ["pending", "ready", "failed"],
+                      "description": "Readiness state. `pending` while provisioning is in flight, `ready` once the set can be bound to a deploy, `failed` if provisioning could not complete."
+                    },
+                    "errorMessage": {
+                      "type": "string",
+                      "description": "Customer-facing message returned only when `status` is `failed`. Generic by design — internal diagnostic details are kept in platform logs."
+                    },
                     "secrets": {
                       "type": "array",
                       "items": {
@@ -58,6 +67,7 @@
                 },
                 "example": {
                   "region": "us-west",
+                  "status": "ready",
                   "secrets": [
                     { "fieldName": "API_KEY" },
                     { "fieldName": "DATABASE_URL" },

diff --git a/pipecat-cloud/fundamentals/error-codes.mdx b/pipecat-cloud/fundamentals/error-codes.mdx
@@ -67,6 +67,23 @@ Indicates an error in your image that prevent your agent from starting. Typicall
 
 This error indicates that the maximum active sessions for your deployment have been reached. You can either increase the maximum active sessions for your deployment (`max-agents`), or place the end-user in a queue until a session becomes available.
 
+### Deploy rejected — secret set not ready (HTTP 409)
+
+> `Secret set 'my-agent-secrets' is not yet ready. Retry once it has been provisioned.`
+
+A deploy that binds a secret set or image pull secret is rejected if the
+referenced set is not in the `ready` state. This guards against the deploy
+appearing to succeed and then failing once the agent tries to start.
+
+- **`pending`**: provisioning is still in flight. Wait a few seconds and
+  retry.
+- **`failed`**: provisioning could not complete. Re-create the secret set
+  or [contact support](mailto:help@daily.co).
+
+See
+[Provisioning and readiness](./secrets#provisioning-and-readiness) for
+how to inspect the status before deploying.
+
 ## Enabling extra logs
 
 If you wish to print a summary of the features available in the base image, set the environment variable `PCC_LOG_FEATURES_SUMMARY` to `true`.

diff --git a/pipecat-cloud/fundamentals/secrets.mdx b/pipecat-cloud/fundamentals/secrets.mdx
@@ -34,6 +34,35 @@ pipecat cloud secrets set my-secrets SECRET_NAME_3 secret-value-3
   using that set will need to be redeployed to access the new values.
 </Info>
 
+#### Provisioning and readiness
+
+Creating or updating a secret set is **asynchronous**. The CLI/API returns
+immediately (HTTP `202 Accepted`) once your values have been stored, but the
+set is then provisioned into the target region in the background. Provisioning
+typically completes within a few seconds.
+
+Each secret set has one of three readiness states:
+
+| Status    | Meaning                                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `pending` | The secret has been accepted but is not yet provisioned in the target region.                                             |
+| `ready`   | The secret is fully provisioned and safe to bind to a deployment.                                                         |
+| `failed`  | Provisioning could not complete. Re-create the secret or [contact support](mailto:help@daily.co) if the problem persists. |
+
+Readiness is included in `GET /v1/secrets` (list) and `GET /v1/secrets/{setName}`
+(single) responses on the [REST API](/api-reference/pipecat-cloud/rest-reference/endpoint/secret-list-all).
+Deploys, updates, and any other operation that binds a secret set to an agent
+are gated on the `ready` state — a request to deploy with a `pending` or
+`failed` set is rejected with HTTP `409 Conflict` rather than failing later
+when the agent starts.
+
+<Tip>
+  In an automated pipeline that creates a secret immediately before deploying
+  (e.g., CI), poll `GET /v1/secrets/{setName}` until `status` is `ready` before
+  triggering the deploy. The window is usually only a few seconds, but guarding
+  the deploy avoids a transient `409`.
+</Tip>
+
 #### Regions
 
 Secret sets are created in a specific region. By default, secrets are created in `us-west` if no region is specified.