docs(api): document the Cloud stacks 429 and drop code comments

Address review on the Cloud portfolio rate-limit fix: document
GET /api/cloud/stacks (including the 429 cloud_portfolio_rate_limited
response and its bounded Retry-After) in docs/api and the OpenAPI
registry, and remove the code comments the PR added.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
paperclipbugbotandClaude Opus 5.5 committed 2026-11-21 11:26:35 +00:00
1 parent 2f319bdadd
commit 6a8f146c55
5 files changed
+38 -6

No files matched your search

+35
View File
@@ -0,0 +1,35 @@
---
title: Cloud Stacks
summary: List the Paperclip Cloud stacks of the signed-in Cloud tenant user
---
This endpoint is available only on a Paperclip Cloud stack. It requires a
trusted Cloud tenant session. Board API keys and agent keys cannot use it.
## List Stacks
```
GET /api/cloud/stacks
```
The server reads the user's stack portfolio from Paperclip Cloud and returns
Cloud's JSON payload unchanged. Responses use `Cache-Control: no-store`. A
successful portfolio is cached on the server for 30 seconds per user.
## Errors
Error bodies have the usual `error` message and a `code`.
| Status | Code | Meaning |
|--------|------|---------|
| 403 | `cloud_tenant_required` | The caller is not a trusted Cloud tenant user |
| 404 | — | This server is not a Paperclip Cloud stack |
| 429 | `cloud_portfolio_rate_limited` | Paperclip Cloud is rate limiting portfolio reads |
| 502 | `cloud_portfolio_upstream_error` | Paperclip Cloud failed or could not be reached |
| 502 | `cloud_portfolio_invalid_response` | Paperclip Cloud returned invalid JSON |
| 503 | `cloud_portfolio_not_configured` | The stack's Cloud connection is not configured |
A `429` response includes `Retry-After` in whole seconds when Paperclip Cloud
supplied a valid hint. The value is between 1 and 300. Wait at least that long
before you try again. A `429` is not cached, so the next request asks Paperclip
Cloud again.
+2 -1
View File
@@ -130,7 +130,8 @@
"api/secrets", "api/secrets",
"api/tool-gateway-tokens", "api/tool-gateway-tokens",
"api/activity", "api/activity",
"api/dashboard" "api/dashboard",
"api/cloud"
] ]
} }
] ]
@@ -87,7 +87,6 @@ describe("GET /api/cloud/stacks", () => {
"Paperclip Cloud portfolio request rate limited", "Paperclip Cloud portfolio request rate limited",
); );
expect(JSON.stringify(warn.mock.calls)).not.toContain("private"); expect(JSON.stringify(warn.mock.calls)).not.toContain("private");
// The throttled answer is not cached: the next read asks Cloud again.
fetchImpl.mockResolvedValueOnce(jsonResponse({ stacks: [] })); fetchImpl.mockResolvedValueOnce(jsonResponse({ stacks: [] }));
expect((await request(app).get("/api/cloud/stacks")).body).toEqual({ stacks: [] }); expect((await request(app).get("/api/cloud/stacks")).body).toEqual({ stacks: [] });
expect(fetchImpl).toHaveBeenCalledTimes(2); expect(fetchImpl).toHaveBeenCalledTimes(2);
-4
View File
@@ -18,7 +18,6 @@ type PortfolioCacheEntry = {
payload: unknown; payload: unknown;
}; };
/** Cloud's Retry-After as bounded whole seconds, or null when absent or malformed. */
function retryAfterSeconds(value: string | null, currentTime: number): number | null { function retryAfterSeconds(value: string | null, currentTime: number): number | null {
const trimmed = value?.trim(); const trimmed = value?.trim();
if (!trimmed) return null; if (!trimmed) return null;
@@ -126,9 +125,6 @@ export function cloudRoutes(opts: {
phase = "http_response"; phase = "http_response";
upstreamStatus = upstream.status; upstreamStatus = upstream.status;
if (upstream.status === 429) { if (upstream.status === 429) {
// Cloud is throttling portfolio reads. That is the control plane's
// backpressure, not a fault here: pass it on with Cloud's retry hint
// instead of answering 502 and reporting a crash.
logger.warn( logger.warn(
{ cloudPortfolio: portfolioError("upstream").diagnostics }, { cloudPortfolio: portfolioError("upstream").diagnostics },
"Paperclip Cloud portfolio request rate limited", "Paperclip Cloud portfolio request rate limited",
+1
View File
@@ -2103,6 +2103,7 @@ registry.registerPath({
200: r.ok(), 200: r.ok(),
403: r.forbidden, 403: r.forbidden,
404: r.notFound, 404: r.notFound,
429: { description: "Paperclip Cloud is rate limiting portfolio reads (code cloud_portfolio_rate_limited). Retry-After, when present, gives whole seconds from 1 to 300. Not cached." },
502: r.serverError, 502: r.serverError,
503: r.serverError, 503: r.serverError,
500: r.serverError, 500: r.serverError,