Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions apps/web/app/api/agent/registrations/[id]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ i
const auth = await authenticateRequestRequireUser(request);
if (!auth.success) return auth.response;
const { id } = await params;
if (!UUID.test(id)) return Response.json({ error: "not_found" }, { status: 404 });
if (!UUID.test(id))
return Response.json(
{ error: "not_found", message: "Connected agent not found" },
{ status: 404 }
);

try {
const revoked = await revokeConnectedAgent(auth.userId, id);
Expand All @@ -27,7 +31,10 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ i
});
return revoked
? new Response(null, { status: 204 })
: Response.json({ error: "not_found" }, { status: 404 });
: Response.json(
{ error: "not_found", message: "Connected agent not found" },
{ status: 404 }
);
} catch (error) {
reportError("DELETE /api/agent/registrations/[id] failed", error);
return Response.json({ error: "Failed to disconnect the agent" }, { status: 500 });
Expand Down
7 changes: 5 additions & 2 deletions apps/web/app/api/attachments/[id]/[index]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ export async function GET(
return Response.json({ error: "invalid_link" }, { status: 403 });
}
if (!isObjectStorageConfigured()) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json({ error: "not_found", message: "Attachment not found" }, { status: 404 });
}

try {
Expand All @@ -55,7 +55,10 @@ export async function GET(
const attachment = email?.attachments[index];
// Gone with the email (retention, or deleted), or never stored.
if (!email?.stored || !attachment) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json(
{ error: "not_found", message: "Attachment not found" },
{ status: 404 }
);
}
const location = await presignGet(
attachmentKey(id, index),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ slug
});

if (!page) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json({ error: "not_found", message: "Endpoint not found" }, { status: 404 });
}

return Response.json(extracts ? { ...page, items: await withEmailExtracts(page.items) } : page);
Expand Down
4 changes: 2 additions & 2 deletions apps/web/app/api/endpoints/[slug]/requests/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ slug
});

if (!data) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json({ error: "not_found", message: "Endpoint not found" }, { status: 404 });
}

return Response.json(extracts ? await withEmailExtracts(data) : data);
Expand Down Expand Up @@ -79,7 +79,7 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ s
});

if (!data) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json({ error: "not_found", message: "Endpoint not found" }, { status: 404 });
}

return new Response(null, { status: 204 });
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,11 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ i
const { id } = await params;
try {
const token = await deleteGoogleConnection(auth.userId, id);
if (token === null) return Response.json({ error: "not_found" }, { status: 404 });
if (token === null)
return Response.json(
{ error: "not_found", message: "Google connection not found" },
{ status: 404 }
);
await revokeToken(token);
await auditUserAction(request, auth.userId, {
action: "integration.google_disconnected",
Expand Down
3 changes: 2 additions & 1 deletion apps/web/app/api/integrations/google/pick/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,8 @@ export async function POST(request: Request) {
const connection = (await listGoogleConnections(auth.userId)).find(
(candidate) => candidate.id === body.connectionId
);
if (!connection) return reply({ error: "not_found" }, 404);
if (!connection)
return reply({ error: "not_found", message: "Google connection not found" }, 404);
const site = parseSite(request.headers.get(SITE_HEADER));
return reply({ url: pickerUrl(config, site, body.nonce, connection.email) });
} catch (error) {
Expand Down
9 changes: 7 additions & 2 deletions apps/web/app/api/request-shares/[id]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ i
if (!auth.success) return auth.response;

const { id } = await params;
if (!isUuid(id)) return Response.json({ error: "not_found" }, { status: 404 });
if (!isUuid(id))
return Response.json({ error: "not_found", message: "Share link not found" }, { status: 404 });

try {
const deleted = await deleteRequestShare(auth.userId, id);
Expand All @@ -19,7 +20,11 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ i
status: deleted ? 200 : 404,
targetId: id,
});
if (!deleted) return Response.json({ error: "not_found" }, { status: 404 });
if (!deleted)
return Response.json(
{ error: "not_found", message: "Share link not found" },
{ status: 404 }
);
return new Response(null, { status: 204 });
} catch (error) {
reportError("Failed to revoke request share", error);
Expand Down
14 changes: 11 additions & 3 deletions apps/web/app/api/requests/[id]/attachments/[index]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,14 @@ export async function GET(

try {
const record = await getRequestByIdForUser(auth.userId, id);
if (!record) return Response.json({ error: "not_found" }, { status: 404 });
if (!record)
return Response.json({ error: "not_found", message: "Request not found" }, { status: 404 });
const attachment = record.email?.attachments[index];
if (record.kind !== "email" || !attachment) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json(
{ error: "not_found", message: "Attachment not found" },
{ status: 404 }
);
}
if (!record.email?.stored || !isObjectStorageConfigured()) {
return Response.json(
Expand All @@ -34,7 +38,11 @@ export async function GET(
);
}
const object = await getObject(attachmentKey(record.id, index));
if (!object?.body) return Response.json({ error: "not_found" }, { status: 404 });
if (!object?.body)
return Response.json(
{ error: "not_found", message: "Attachment not found" },
{ status: 404 }
);
const length = object.headers.get("content-length");
return new Response(object.body, {
headers: {
Expand Down
3 changes: 2 additions & 1 deletion apps/web/app/api/requests/[id]/raw/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ export async function GET(request: Request, { params }: { params: Promise<{ id:
const { id } = await params;
try {
const record = await getRequestByIdForUser(auth.userId, id);
if (!record) return Response.json({ error: "not_found" }, { status: 404 });
if (!record)
return Response.json({ error: "not_found", message: "Request not found" }, { status: 404 });
if (record.kind !== "email" || !record.email) {
return Response.json({ error: "not_an_email" }, { status: 400 });
}
Expand Down
4 changes: 2 additions & 2 deletions apps/web/app/api/requests/[id]/render/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,11 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
if (key !== undefined && key !== null && (typeof key !== "string" || key.length > 200)) {
return reply({ error: "mailgunSigningKey is text of at most 200 characters." }, 400);
}
if (!isUuid(id)) return reply({ error: "not_found" }, 404);
if (!isUuid(id)) return reply({ error: "not_found", message: "Request not found" }, 404);

try {
const captured = await getRequestByIdForUser(auth.userId, id);
if (!captured) return reply({ error: "not_found" }, 404);
if (!captured) return reply({ error: "not_found", message: "Request not found" }, 404);
if (captured.kind !== "email" || !captured.email) {
return reply({ error: "Only a captured email can be rendered in a provider's shape." }, 400);
}
Expand Down
9 changes: 6 additions & 3 deletions apps/web/app/api/requests/[id]/replay/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
const reply = (body: unknown, status = 200) =>
applyRateLimitHeaders(Response.json(body, { status }), rateLimit);

if (!/^[0-9a-f-]{36}$/i.test(id)) return reply({ error: "not_found" }, 404);
if (!/^[0-9a-f-]{36}$/i.test(id))
return reply({ error: "not_found", message: "Request not found" }, 404);
try {
const { data, error } = await createAdminClient()
.from("requests")
Expand All @@ -32,10 +33,12 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
endpoints: { user_id: string | null; slug: string };
}>();
if (error) throw error;
if (!data || data.endpoints.user_id !== auth.userId) return reply({ error: "not_found" }, 404);
if (!data || data.endpoints.user_id !== auth.userId)
return reply({ error: "not_found", message: "Request not found" }, 404);
// Past retention it is gone, whether or not the cleanup has deleted it yet.
const retained = await getRetainedRequestsByIds(data.endpoint_id, [data.id]);
if (retained.length === 0) return reply({ error: "not_found" }, 404);
if (retained.length === 0)
return reply({ error: "not_found", message: "Request not found" }, 404);
const queued = await replayRequests(data.endpoint_id, [data.id]);
await auditUserAction(request, auth.userId, {
action: "request.replayed",
Expand Down
2 changes: 1 addition & 1 deletion apps/web/app/api/requests/[id]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ id:
try {
const data = await getRequestByIdForUser(auth.userId, id);
if (!data) {
return Response.json({ error: "not_found" }, { status: 404 });
return Response.json({ error: "not_found", message: "Request not found" }, { status: 404 });
}

return Response.json(extracts ? (await withEmailExtracts([data]))[0] : data);
Expand Down
16 changes: 9 additions & 7 deletions apps/web/app/api/requests/[id]/shares/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ import { isUuid } from "@/lib/uuid";
// approval, lib/approvals). Listing them takes any key of the account.

const SHARE_ERRORS = {
not_found: { status: 404, message: "not_found" },
email: { status: 400, message: "Emails cannot be shared" },
not_owner: { status: 403, message: "Only the endpoint's owner can share its requests" },
not_found: { status: 404, body: { error: "not_found", message: "Request not found" } },
email: { status: 400, body: { error: "Emails cannot be shared" } },
not_owner: { status: 403, body: { error: "Only the endpoint's owner can share its requests" } },
limit: {
status: 409,
message: `You can have ${MAX_ACTIVE_SHARES} live share links. Revoke some first.`,
body: { error: `You can have ${MAX_ACTIVE_SHARES} live share links. Revoke some first.` },
},
} as const;

Expand Down Expand Up @@ -62,7 +62,9 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
}
const hideSensitive = body.hideSensitive !== false;

if (!isUuid(id)) return Response.json({ error: "not_found" }, { status: 404 });
if (!isUuid(id)) {
return Response.json({ error: "not_found", message: "Request not found" }, { status: 404 });
}

// An API key or agent token: the account's owner approves the link first.
if (auth.keyId) {
Expand All @@ -82,14 +84,14 @@ export async function POST(request: Request, { params }: { params: Promise<{ id:
hideSensitive,
});
if (!result.ok) {
const { status, message } = SHARE_ERRORS[result.error];
const { status, body: answer } = SHARE_ERRORS[result.error];
await auditUserAction(request, auth.userId, {
action: "request.share_created",
status,
targetId: id,
reason: result.error,
});
return Response.json({ error: message }, { status });
return Response.json(answer, { status });
}

await auditUserAction(request, auth.userId, {
Expand Down
8 changes: 8 additions & 0 deletions apps/web/changelog/web/readable-not-found-errors.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"title": "Readable not-found errors",
"items": [
"A not_found answer carries a readable message beside its code (\"Request not found\", \"Endpoint not found\", \"Attachment not found\", \"Share link not found\", \"Connected agent not found\", \"Google connection not found\") on the request, endpoint request list, attachment, share link, connected agent and Google connection routes",
"The hosted MCP server calls a refusal because something already exists or is in use (HTTP 409) a conflict rather than a validation error",
"The changelog lists SDK 1.31.1"
]
}
15 changes: 14 additions & 1 deletion apps/web/lib/changelog.ts
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ const RELEASE = release as { version: string | null; entries: ChangelogEntry[] }

export const APP_VERSION: string = RELEASE.version ?? "dev";
export const CLI_VERSION = "1.20.1";
export const SDK_VERSION = "1.31.0";
export const SDK_VERSION = "1.31.1";
export const PYTHON_SDK_VERSION = "0.10.1";
export const GO_SDK_VERSION = "0.10.1";
export const MCP_VERSION = "2.5.0";
Expand Down Expand Up @@ -2546,6 +2546,15 @@ export const CHANGELOG: ChangelogEntry[] = [
},

// ─── SDK ────────────────────────────────────────────────────────────
{
version: "1.31.1",
date: "2026-11-16",
title: "Readable Errors For Bare Codes",
track: "sdk",
items: [
'An error whose body names only a code (`{ "error": "not_found" }`) reads as the status in words, with its hint, instead of the code alone: "Not found" when the code only names the status, and the code in brackets when it says more ("Bad request (invalid_since)"); the code is still the error\'s `code`',
],
},
{
version: "1.31.0",
date: "2026-11-16",
Expand Down Expand Up @@ -3041,6 +3050,7 @@ export const CHANGELOG: ChangelogEntry[] = [
items: [
"An error's `message` is the API's text, not its JSON: the `message` of a JSON error body, else its `error`, so a long answer is no longer cut into broken JSON",
"A duration string too long or too large for a float (400 digits, or a huge value with a unit) raises the invalid-duration `ValueError` instead of becoming an endless wait",
'An error whose body names only a code (`{"error": "not_found"}`) reads as the status in words instead of the code alone: "Not found" when the code only names the status, and the code in brackets when it says more ("Bad request (invalid_since)"); `InvalidCursorError` and `RateLimitError.code` still read the code',
],
},
{
Expand Down Expand Up @@ -3192,6 +3202,7 @@ export const CHANGELOG: ChangelogEntry[] = [
track: "go",
items: [
'An `Error`\'s `Message` is the API\'s text, not its JSON: the `message` of a JSON error body, else its `error`, so a long answer is no longer cut into broken JSON; a short one gets its hint after ": " (404) or ". " (401), as in the other SDKs, and `errors.Is(err, ErrInvalidCursor)` reads the body\'s code as before',
'An error whose body names only a code (`{"error":"not_found"}`) reads as the status in words instead of the code alone: "Not found" when the code only names the status, and the code in brackets when it says more ("Bad request (invalid_since)"); `errors.Is(err, ErrInvalidCursor)` still reads the code',
],
},
{
Expand Down Expand Up @@ -3326,6 +3337,8 @@ export const CHANGELOG: ChangelogEntry[] = [
"`describe` answers the SDK version and its sections' operation names (about 2.5 KB, from 33 KB); `section` returns one section's parameters and types",
"The tool list is smaller: conditions of response rules, filters and layouts are described once per list, a rule's response once as `mockResponse`, and input schemas leave out the `$schema` URI (MCP reads JSON Schema 2020-12 without it). The core list is 59.1 KB as sent (from 63.4 KB), the full one 119.3 KB (from 128.1 KB)",
"On the hosted server, names in `?tools=` that are no group are reported on `describe` and in the instructions, and when none of the names is a group the client's own default applies rather than the core",
'An API error that names only a code reads as the status in words ("Not found" for a request id that does not exist, with the `list_requests` hint), keeping the code in brackets when it says more ("Bad request (invalid_since)")',
"A refusal because something already exists or is in use (HTTP 409) has the tool error code `conflict`, not `validation_error`",
],
},
{
Expand Down
2 changes: 1 addition & 1 deletion content/docs/sdk/api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1997,6 +1997,6 @@ import {

`WebhooksCCError.code` is the API's own error code when its answer had one, such as `"invalid_cursor"` or `"search_busy"` from `requests.searchPage()`.

`message` is what the API said as plain text (the `message` of a JSON error body, else its `error`), followed by the SDK's recovery hint when the text is short. `apiMessage` is the same text without the hint, and `path` is the API route that answered, after `/api` (such as `/endpoints/acme`); both are set on errors made from an API answer.
`message` is what the API said as plain text (the `message` of a JSON error body, else its `error`; when that is only a code (`not_found`), the status in words, with the code in brackets when it says more (`Bad request (invalid_since)`), and `code` still holds it when it came from `error`), followed by the SDK's recovery hint when the text is short. `apiMessage` is the same text without the hint, and `path` is the API route that answered, after `/api` (such as `/endpoints/acme`); both are set on errors made from an API answer.

`WebhookVerificationError.code` is `"missing_headers"`, `"timestamp_out_of_range"`, `"invalid_signature"` or `"invalid_payload"`. Answer the first three with 401 and `invalid_payload` with 400.
2 changes: 1 addition & 1 deletion content/docs/sdk/go.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -466,7 +466,7 @@ client, err := connection.Wait(ctx)

## Errors

API errors are a `*webhookscc.Error` with a `StatusCode` and a `Message`, the API's own text (the `message` of a JSON error body, else its `error`) with a recovery hint when it is short. Test them with `errors.Is`:
API errors are a `*webhookscc.Error` with a `StatusCode` and a `Message`, the API's own text (the `message` of a JSON error body, else its `error`; when that is only a code (`not_found`), the status in words, with the code in brackets when it says more (`Bad request (invalid_since)`)) with a recovery hint when it is short. Test them with `errors.Is`:

| Error | When |
| ----------------------------- | --------------------------------------------------------------- |
Expand Down
2 changes: 1 addition & 1 deletion content/docs/sdk/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -377,7 +377,7 @@ client = pending.wait()

## Errors

API errors raise `WebhooksCCError` with a `status_code` and a `message`, the API's own text (the `message` of a JSON error body, else its `error`) with a recovery hint when it is short, or one of its subclasses:
API errors raise `WebhooksCCError` with a `status_code` and a `message`, the API's own text (the `message` of a JSON error body, else its `error`; when that is only a code (`not_found`), the status in words, with the code in brackets when it says more (`Bad request (invalid_since)`)) with a recovery hint when it is short, or one of its subclasses:

| Error | When |
| -------------------- | ------------------------------------------------------------- |
Expand Down
Loading
Loading