Skip to content

fix(sdk): readable error text when the API answers only a code, sdk 1.31.1 - #729

Merged
kroqdotdev merged 3 commits into
mainfrom
fix/sdk-code-only-errors
Nov 16, 2026
Merged

kroqdotdev merged 3 commits into
mainfrom
fix/sdk-code-only-errors

Conversation

@kroqdotdev

@kroqdotdev kroqdotdev commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

#728 made the SDKs take an API error's text from the body (message, else error). Routes that answer only a code, such as GET /api/requests/{unknown id} with {"error":"not_found"}, then gave message: "not_found" in the SDK and the MCP tools.

  • TypeScript SDK (mapStatusToError): when the extracted text is a bare code (/^[a-z][a-z0-9_]*$/), the message is the status in words: 400 "Bad request", 401 "Unauthorized", 403 "Forbidden", 404 "Not found", 409 "Conflict", 429 "Too many requests", 5xx "Server error", any other "Request failed with HTTP n". The words stand alone only when the code just names the status (not_found on a 404, unauthorized on a 401); otherwise the code follows in brackets, since it says what went wrong: "Bad request (invalid_since)", "Server error (internal_error)", "Request failed with HTTP 410 (expired)". This applies to a message that is only a code too. The short-message hint is still added, and code is still read from the body.

  • Python SDK (_error_from_response) and Go SDK (errorFromResponse): the same rule. InvalidCursorError, RateLimitError.code and errors.Is(err, ErrInvalidCursor) still read the code.

  • MCP: get_request on an unknown id now answers message: "Not found" with the list_requests hint (new test). A 409 now has the tool error code conflict instead of validation_error (ToolErrorCode gains conflict).

  • Web routes: these answer a readable message beside error: "not_found", which stays as it was so clients matching the code keep working:

    • requests/[id], requests/[id]/raw, requests/[id]/replay, requests/[id]/render and requests/[id]/shares: "Request not found"
    • requests/[id]/attachments/[index]: "Request not found" or "Attachment not found"
    • endpoints/[slug]/requests and endpoints/[slug]/requests/paginated: "Endpoint not found"
    • attachments/[id]/[index] (signed links): "Attachment not found"
    • request-shares/[id]: "Share link not found"
    • agent/registrations/[id]: "Connected agent not found"
    • integrations/google/connections/[id] and integrations/google/pick: "Google connection not found"

    Each entry in SHARE_ERRORS in the share route now holds its whole response body.

  • Docs: the error sections of the TypeScript, Python and Go SDK pages describe the rule (and, for TypeScript, that code still holds it when it came from error).

  • Test fixtures that used a one-word lower-case message ("y" * 250, "busy") now count as codes, so they were changed to sentences; the "another 400" tests check that invalid_q is still in the message.

Versions

  • SDK 1.31.0 is already on npm, so this bumps it to 1.31.1 (package.json, SDK_VERSION, changelog entry).
  • MCP 2.5.0, Python 0.10.1 and Go 0.10.1 are not published yet: they keep those versions, and their changelog entries get one more line each.
  • Web changelog file readable-not-found-errors.json, label release: patch.

Checks

  • pnpm typecheck, pnpm lint and pnpm test (SDK 1016, MCP 263, web 2593) all pass
  • Python: uv run pytest (941), ruff check, ruff format --check and mypy all pass
  • Go: go vet ./... and go test -race ./... pass
  • Prettier is clean on the changed files

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • API responses for missing requests and attachments now include clear, readable messages while retaining their existing error codes and status codes.
    • TypeScript, Python, and Go SDKs now display human-readable messages when an API response contains only an error code, while preserving access to the code. Known error codes continue to receive relevant handling, including endpoint guidance where available.

….31.1

A body such as {"error":"not_found"} no longer becomes the error's message.
The TypeScript, Python and Go SDKs say the status in words instead ("Not
found", "Bad request", "Server error", ...) and keep the code where it was
read before (code, InvalidCursorError, RateLimitError.code,
ErrInvalidCursor). The request routes also answer a readable message beside
their not_found code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kroqdotdev kroqdotdev added the release: patch Ships a fix or small feature: the next web release bumps the patch version label Nov 16, 2026
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Request routes now include descriptive messages in 404 responses. TypeScript, Go, and Python SDK clients replace bare error codes with status-derived messages while retaining error codes. The changelog and SDK version reflect these updates.

Changes: Readable API errors

Layer / File(s) Summary
Request route error messages
apps/web/app/api/requests/[id]/*/route.ts, apps/web/app/api/requests/[id]/route.ts, apps/web/changelog/web/readable-not-found-errors.json
Request routes add descriptive messages to missing-request and missing-attachment 404 responses. The web changelog records the route changes.
TypeScript SDK error mapping
packages/sdk/src/client.ts, packages/sdk/src/__tests__/*, packages/sdk/package.json, apps/web/lib/changelog.ts
The SDK maps code-only error text to status-derived messages and retains the error code. Tests cover the mapping, and the SDK version and changelog are updated.
Go, Python, and MCP error handling
packages/sdk-go/*, packages/sdk-python/src/webhooks_cc/client.py, packages/sdk-python/tests/test_client.py, packages/mcp/src/__tests__/tools.test.ts, apps/web/lib/changelog.ts
The Go and Python SDKs map code-only errors to status-derived messages while preserving code handling. Tests cover these mappings and the MCP not-found response. Changelog entries describe the behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: Minimal · up to 46f86

This change makes API errors more readable in the SDKs and MCP tools by replacing bare error codes with status-based messages while keeping the codes. No concrete merge-blocking risk was found.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: when the API answers with only an error code, the SDK shows readable error text. It also names the SDK version bump. The changeset does include the readable-message ch…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Full details: Title check

Explanation

The title names the main change: when the API answers with only an error code, the SDK shows readable error text. It also names the SDK version bump. The changeset does include the readable-message change across the TypeScript, Python, and Go SDKs, the MCP tools, and the request routes, so the title matches the primary change. The title is specific and uses the conventional commit format.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ab0ee53c-b3de-4264-889d-fd6b6c6da59e
Commits

Reviewing files that changed from the base of the PR and between 701533a and 46f864f.

Files selected for processing: 17

  • apps/web/app/api/requests/[id]/attachments/[index]/route.ts
  • apps/web/app/api/requests/[id]/raw/route.ts
  • apps/web/app/api/requests/[id]/render/route.ts
  • apps/web/app/api/requests/[id]/replay/route.ts
  • apps/web/app/api/requests/[id]/route.ts
  • apps/web/changelog/web/readable-not-found-errors.json
  • apps/web/lib/changelog.ts
  • packages/mcp/src/__tests__/tools.test.ts
  • packages/sdk-go/client.go
  • packages/sdk-go/client_test.go
  • packages/sdk-go/internal_test.go
  • packages/sdk-python/src/webhooks_cc/client.py
  • packages/sdk-python/tests/test_client.py
  • packages/sdk/package.json
  • packages/sdk/src/__tests__/checkouts.test.ts
  • packages/sdk/src/__tests__/client.test.ts
  • packages/sdk/src/client.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@github-actions

Copy link
Copy Markdown

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

@kroqdotdev

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

kroqdotdev and others added 2 commits November 16, 2026 01:44
Review round 1 on #729. A bare-code error now reads as the status in
words alone only when the code just names the status (not_found on a
404); otherwise the code follows in brackets ("Bad request
(invalid_since)"), the same in the TypeScript, Python and Go SDKs. The
unknown-status fallback reads "Request failed with HTTP 410". The share
route answers "Request not found" beside not_found, the SDK docs describe
the rule, and the "another 400" tests check the code is still in the
message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nflict

Review round 2 on #729. The endpoint request lists, attachment links,
share links, connected agents and Google connection routes answer a
readable message beside error "not_found", which stays as it was. The
share route's errors carry their whole body in SHARE_ERRORS. MCP tool
errors call a 409 "conflict" instead of "validation_error". The SDK docs
say `code` holds the code only when it came from `error`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kroqdotdev
kroqdotdev merged commit 57b0f47 into main Nov 16, 2026
37 checks passed
@kroqdotdev
kroqdotdev deleted the fix/sdk-code-only-errors branch November 16, 2026 01:05
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 16, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

release: patch Ships a fix or small feature: the next web release bumps the patch version

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant