docs: crosslink API error references#166
Conversation
Add focused links from cloud agent, CLI, integration, billing, and API docs to the relevant API/SDK troubleshooting error pages. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This documentation PR adds focused crosslinks from Cloud Agents, integrations, CLI, API/SDK, and billing guidance to the API error reference pages. I checked the changed links against the local docs tree, reviewed the content for documentation accuracy and style, applied the supplemental security pass, and found no blocking issues.
Concerns
- No general review concerns found.
- No material spec-alignment concerns found; the provided spec context states that no approved or repository spec context was found.
- No security concerns found; this PR only updates documentation links and explanatory text.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
left a comment
hongyi-chen
left a comment
There was a problem hiding this comment.
Approved, but high-level feedback:
I think we should audit each of the errors we’re surfacing. Some of them may not be necessary to call out explicitly. For example, if we’re already in a billing section talking about running out of credits, I don’t think we need to also mention that users will see an “insufficient credits” error.
I’d also be careful about embedding too many error message references throughout canonical docs pages. I like the tips approach, but I’d lean toward putting these in a dedicated section at the bottom of the page, like “Troubleshooting,” rather than weaving them into the main flow everywhere.
| 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/) - Learn how each integration behaves, how agents are triggered, and what teammates see in those tools. |
There was a problem hiding this comment.
We should also reference the other integrations available as well
|
|
||
| * Runs are not tied to any individual user. | ||
| * On Build, Max, and Business plans, Warp bills the team owner: 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 add-on credit pool subject to the team-wide monthly spend cap. | ||
| * On Build, Max, and Business plans, Warp bills the team owner: 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, which can return [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/). With auto-reload on, usage can trigger a reload on the owner's add-on credit pool subject to the team-wide monthly spend cap. |
There was a problem hiding this comment.
I don't think we always need to surface these insufficient-credits mentions, it's pretty straightforward and I don't think it's necessary to include here
| Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@Oz** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. | ||
|
|
||
| When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. | ||
| When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. Missing authorization can return [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/). |
There was a problem hiding this comment.
Generally, I don't think we should include this many error cases embedded throughout the canonical pages - I think we can have a troubleshooting section at the bottom of these pages, but if I'm setting up an integration, billing, or a team, etc, I don't think I need to know about the error codes everywhere throughout. I would probably go to a troubleshooting or separate section
2 participants
Summary
warp_api_keyworkflow example.Validation
git diff --checknpm run typecheck(passes with existing hints)npm run build(passes with existing non-blocking Astro prerender warnings)npm run lintnot run:trunkis not installed in this environmentArtifacts
Co-Authored-By: Oz oz-agent@warp.dev