docs: crosslink API error references

src/content/docs/agent-platform/cloud-agents/environments.mdx

@@ -290,12 +290,12 @@ If your setup commands depend on secrets or credentials, configure them through
 
 ### Common issues
 
-* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable.
+* **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. Setup failures can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/).
   * Solution: Write idempotent setup commands that work on a fresh container.
 * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization.
   * Solution: Configure credentials with [Agent Secrets](/agent-platform/cloud-agents/secrets/).
-* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions.
+* **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn't have repo access or the triggering user lacks permissions. Missing external authorization can surface as [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/).
   * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup.
 * **Docker image incompatibility** – You see the error: "VM failed before the agent could run. This is likely an issue with your Docker image."
-  * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc.
+  * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. This can surface as [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/).
   * Solution: Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`).

src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx

@@ -65,6 +65,12 @@ You can specify a skill using the `skill` input parameter, either instead of or
     warp_api_key: ${{ secrets.WARP_API_KEY }}
 ```
 
+:::tip
+If the action fails, use the returned error code to narrow the fix. Common errors include:
+
+* [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) (missing, invalid, or expired `warp_api_key` secret)
+:::
+
 #### Skill format options
 
 The `skill` parameter supports multiple formats for referencing skills:

src/content/docs/agent-platform/cloud-agents/integrations/index.mdx

@@ -13,7 +13,7 @@ Warp integrations let your team trigger agents directly from the terminal, or fr
 * Run code inside your codebase in a remote environment
 * Open pull requests and perform other multi-step agent workflows on your behalf
 
-If you're deciding whether an agent should run from a schedule, Slack or Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/).
+If you're deciding whether an agent should run from a schedule, Slack, Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/).
 
 :::note
 For a full walkthrough of Warp's integrations and configurable environments, please refer to [Integration setup](/reference/cli/integration-setup/).
@@ -23,86 +23,15 @@ All of this is powered by the [Oz CLI](/reference/cli/).
 
 ---
 
-## Quickstart
+## Get started
 
-The fastest way to get agents running from Slack or Linear is to create an environment with the guided flow. An **environment** defines everything the agent needs to run your code remotely, including your Docker image, repos, and setup commands.
+Use the setup walkthrough below for a quick look at how environments connect to integrations, then choose the guide that matches what you want to do next.
 
 <VideoEmbed url="https://www.youtube.com/watch?v=ahFfInVD0HQ" />
 
-#### 1. Run /create-environment
-
-From Warp, run the following slash command:
-
-```
-/create-environment
-```
-
-You can run it inside any repo, or point it at multiple repos:
-
-```
-/create-environment ./frontend ./backend
-/create-environment your-org/repo-name
-/create-environment https://github.com/your-org/api.git
-```
-
-:::note
-Learn more about slash commands and how to use them in the [Slash Commands](/agent-platform/capabilities/slash-commands/) documentation.
-:::
-
-The guided flow will:
-
-* Detect which repos you want the agent to work with
-* Identify languages, frameworks, and tools
-* Suggest a Docker image (or build/push one if needed)
-  * The Docker image can be your own custom image, an official base image (e.g. node, python), or one of Warp's prebuilt dev images (see [repo](https://github.com/warpdotdev/oz-dev-environments)).
-* Recommend setup commands
-* Create the environment and return an environment ID
-
-This produces a ready-to-use environment that Warp can use across Slack, Linear, and terminal triggers.
-
-#### 2. Authorize GitHub
-
-Warp will prompt you to install or update the Warp GitHub app so the agent can read and write to the repos you included. You only need to do this once. Teammates will authorize on their first run as needed.
-
-:::note
-**Using Azure DevOps, GitLab, or Bitbucket?** Native integrations for these platforms are not yet available, but you can connect repositories by storing a personal access token as a Warp-managed secret and cloning via a setup command. See [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/), [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), or [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) for step-by-step instructions.
-:::
-
-#### 3. Create an integration
-
-:::note
-For easier setup, use the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) to configure integrations with a guided flow. The web app works on mobile devices.
-:::
-
-Alternatively, use the CLI:
-
-For Slack:
-
-```
-oz integration create slack --environment <ENV_ID>
-```
-
-For Linear:
-
-```
-oz integration create linear --environment <ENV_ID>
-```
-
-The CLI opens an authorization page where you install Oz into your Slack workspace or Linear team.
-
-#### 4. Start using agents
-
-In Slack:
-
-* Tag **@Oz** in a message or thread
-* Or DM the bot
-
-In Linear:
-
-* Tag @Oz on an issue
-
-Warp will read the thread/issue, spin up your environment, run the workflow in the cloud, and post progress + PRs back into the same conversation.
-
----
-
-For more details on configuring integrations and environments in Warp, please refer to [Integration setup](/reference/cli/integration-setup/).
+* [Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/) - Trigger your first agent from Slack and watch the run from start to finish.
+* [Integration setup](/reference/cli/integration-setup/) - Configure environments, GitHub authorization, CLI flags, and integrations in more detail.
+* [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) - Trigger agents from team conversations, issues, and comments.
+* [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) - Run agents from CI workflows and repository events.
+* [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/), and [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/) - Connect non-GitHub repositories with tokens and Warp-managed secrets.
+* [AWS, GCP, and other cloud providers](/agent-platform/cloud-agents/integrations/cloud-providers/) - Give cloud agents short-lived access to cloud services.

src/content/docs/agent-platform/cloud-agents/integrations/linear.mdx

@@ -110,6 +110,13 @@ oz integration create linear --environment <ENV_ID>
 
 The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team.
 
+:::tip
+If the integration cannot be created or a Linear-triggered run cannot start, use the returned error code to narrow the fix. Common errors include:
+
+* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations)
+* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Linear authorization)
+:::
+
 ---
 
 ### Uninstallation instructions
@@ -124,7 +131,7 @@ To remove the Oz integration from Linear:
 
 <VideoEmbed url="https://www.loom.com/share/2f1648586d8148dc80561c00a09ca334" />
 
-After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup.
+After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/).
 
 ### Troubleshooting
 

src/content/docs/agent-platform/cloud-agents/integrations/quickstart.mdx

@@ -43,6 +43,13 @@ oz integration create slack --environment <ENV_ID>
 
 Replace `<ENV_ID>` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace.
 
+:::tip
+If the integration cannot be created or your first run cannot start, use the returned error code to narrow the fix. Common errors include:
+
+* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations)
+* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization)
+:::
+
 To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag:
 
 ```bash

src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx

@@ -135,6 +135,13 @@ oz integration create slack --environment <ENV_ID>
 
 The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team.
 
+:::tip
+If the integration cannot be created or a Slack-triggered run cannot start, use the returned error code to narrow the fix. Common errors include:
+
+* [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) (plan does not support integrations)
+* [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) (missing GitHub or Slack authorization)
+:::
+
 You can optionally attach a custom prompt that is applied to every agent run:
 
 ```
@@ -170,7 +177,7 @@ To remove the Oz app from your Slack workspace:
 
 ![Confirmation dialog to remove the Oz app from a Slack workspace.](../../../../../assets/agent-platform/remove-slack-app.png)
 
-Once removed, Slack will immediately disable the integration for all teammates.
+Once removed, Slack will immediately disable the integration for all teammates. Events for a disabled integration can return [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/).
 
 ### Troubleshooting
 

src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx

@@ -90,7 +90,7 @@ Where the agent was launched from. Common sources include:
 
 Warp uses a small set of statuses to help you quickly identify what needs attention:
 
-<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><code>Failed / Errored</code></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table>
+<table><thead><tr><th width="173.375">Status</th><th width="78.41973876953125">Icon</th><th>Description</th></tr></thead><tbody><tr><td><code>Working</code></td><td>N/A</td><td>in progress (may include queued / running states)</td></tr><tr><td><code>Blocked</code></td><td>🟨</td><td><p><em>(interactive only)</em></p><p><br />the conversation is waiting on user input or a required step</p></td></tr><tr><td><code>Canceled</code></td><td>⬜️</td><td>(interactive only)<br /><br />the interactive conversation was canceled before completion</td></tr><tr><td><a href="/reference/api-and-sdk/troubleshooting/errors/"><code>Failed / Errored</code></a></td><td>🔺</td><td>something went wrong (applies to both interactive and cloud agent runs)</td></tr><tr><td><code>Success</code></td><td>✅</td><td>completed successfully (applies to both interactive and cloud agent runs)</td></tr></tbody></table>
 
 **Duration (for cloud agent tasks)**
 

src/content/docs/agent-platform/cloud-agents/quickstart.mdx

@@ -151,13 +151,13 @@ Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatical
 ## Troubleshooting
 
 **Environment creation fails**\
-Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images.
+Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images and [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) for the related API error.
 
 **Agent can't access repos**\
-Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`.
+Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works) and [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get <ENV_ID>`; permission mismatches can surface as [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/).
 
 **Not enough credits to run cloud agents**\
-Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents.
+Your team needs at least 20 credits available. Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. If a run is blocked because the billed principal has no remaining credits, see [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/).
 
 **More resources**
 

src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx

@@ -82,7 +82,7 @@ Your team must meet the following requirements to run integrations:
 When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits based on who the run is billed to:
 
 * **User-triggered runs on Build, Max, or Business** - Warp draws from any [cloud agent credits](/support-and-community/plans-and-billing/credits/#compute-credits) the user has, then the user's plan-included credits, then the user's add-on credits. Add-on credits are scoped to the individual user and are not shared across the team.
-* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap.
+* **Team API key or scheduled cloud agent runs on Build, Max, or Business** - Warp bills the team owner. The waterfall is: the owner's plan-included credits, then the owner's add-on credits. With auto-reload off, the request is blocked when both pools are depleted. With auto-reload on, usage can trigger a reload on the owner's pool subject to the team-wide monthly spend cap; once the cap is reached, runs are blocked until the cap resets or increases.
 * **Enterprise plans** - Runs draw from the team-scoped credit pool, per your Enterprise contract terms.
 
 If all applicable credit sources are exhausted and no auto-reload is configured, integrations and cloud agents will not run until credits are added. See [add-on credits](/support-and-community/plans-and-billing/add-on-credits/) for the full self-serve waterfall and [platform credits](/support-and-community/plans-and-billing/platform-credits/) for the third bucket that applies to every cloud agent run.
@@ -197,7 +197,7 @@ Warp’s behavior in GitHub is defined by two layers of control:
 **In practice, agents can only operate on repositories that:**
 
 * Are included in the environment configuration
-* Are accessible to both the GitHub app and the triggering user
+* Are accessible to both the GitHub app and the triggering user.
 
 ---
 
@@ -251,6 +251,16 @@ It's the team's responsibility to manage triggers, confirm they behave as intend
 
 ---
 
+## Troubleshooting
+
+If a cloud agent or integration run fails with an error code, use the error reference to narrow the fix:
+
+* **Missing GitHub or external authorization** - See [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) when a user needs to authorize GitHub, Slack, or Linear before a run can continue.
+* **Insufficient repo permissions** - See [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) when the triggering user or GitHub App lacks access to the repo the agent needs.
+* **Credits or spend caps block a run** - See [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) or [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) when the billed account has depleted credits or reached a configured spend cap.
+
+---
+
 ## Related resources
 
 * [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) - How user-scoped add-on credits, auto-reload, and the team-wide spend cap work on self-serve plans.