docs(signal): distinguish AgentKit tool-execution errors from Scalekit auth failures - #939
docs(signal): distinguish AgentKit tool-execution errors from Scalekit auth failures#939saif-at-scalekit wants to merge 1 commit into
Conversation
WalkthroughThe AgentKit Node.js and Python SDK error guides now document tool execution failures, exception handling, diagnostic logging, retry guidance, and recommended responses for provider and Scalekit credential errors. ChangesAgentKit tool error documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/content/docs/agentkit/sdks/node/errors.mdx`:
- Around line 67-94: Import the Code component once in
src/content/docs/agentkit/sdks/node/errors.mdx and replace the untitled fenced
sample around lines 67-94 with Code, setting its title to the example file path.
Apply the same change in src/content/docs/agentkit/sdks/python/errors.mdx around
lines 65-90, using that sample’s example file path as the title.
- Around line 65-89: Update the diagnostic logging in the Node example’s
isToolException() branch to include err.toolErrorMessage alongside toolErrorCode
and executionId. Also update the Python example at
src/content/docs/agentkit/sdks/python/errors.mdx lines 63-89 to include
e.tool_error_message alongside the existing provider error fields.
- Around line 60-101: Update both error examples in
src/content/docs/agentkit/sdks/node/errors.mdx (lines 60-101) and
src/content/docs/agentkit/sdks/python/errors.mdx (lines 58-97): make each
gmail_send_email call runnable by passing to, subject, and body through params,
add title attributes to both fenced code blocks, and include toolErrorMessage
alongside the existing diagnostic fields in logging. Ensure the corresponding
language-specific syntax remains valid.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 382cd2f3-872c-4f05-80cf-31d6fa906144
📒 Files selected for processing (2)
src/content/docs/agentkit/sdks/node/errors.mdxsrc/content/docs/agentkit/sdks/python/errors.mdx
📜 Review details
🧰 Additional context used
📓 Path-based instructions (13)
**/*.mdx
📄 CodeRabbit inference engine (.cursorrules)
**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component:1. ## Titlewith all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
⚙️ CodeRabbit configuration file
**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:Frontmatter
titleMUST be ≤ 60 characters and clearly state what the page does.descriptionMUST be ≤ 160 characters, action-oriented, unique per page.sidebar.labelMUST be present and ≤ 30 characters.sidebar.orderMUST be set on every page that lives inside a section
with siblings, to enforce the journey order in sidebar.config.ts.- Flag any missing
prev/nextlinks on pages that are clearly
part of a sequential flow (e.g., quickstart → implement-login →
complete-login → manage-session → logout).Voice & Style (CLAUDE.md standards)
- Voice: confident, direct, collaborative, instructional.
- Person: second person only ("you", "your application"). Reject "we",
"our", "the developer", "the user".- Tense: present tense for descriptions; imperative mood for instructions.
- Flag weasel words: "simply", "just", "easy", "straightforward",
"obviously", "of course", "note that".- Flag passive voice constructions where active voice is clearer.
- Headings must be sentence case, not Title Case (except proper nouns).
- Headings that match a real API parameter, method, or field name
(e.g.,contactID,xero_tenant_id,executeTool) should preserve
the original casing. Do NOT flag these as sentence-case violations.- No heading should end with a colon or period.
Content structure
- Journey how-to guides MUST contain numbered
<Steps>(Starlight
component). This does NOT apply tosrc/content/docs/cookbooks/**
(blog-style recipes — optional<Steps>,<Tabs>after</Steps>OK;
see cookbookspath_instructions).- Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
- API reference pages MUST list parameters in a table with Name / Type /
Required / Description columns.- Every page MUST end with a clear "what's next" signal — either a
next:f...
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*.{yml,yaml,md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)
**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*.{md,mdx}
📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)
**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
src/content/docs/**/*.mdx
📄 CodeRabbit inference engine (.cursor/rules/starlight-steps-tabs-structure.mdc)
src/content/docs/**/*.mdx: In MDX documentation files,<Steps>must contain one continuous ordered list. Wrap<Steps>around a normal Markdown ordered list such as1. ## ...
In MDX documentation files, numbered step lines must start at column 0. Do not indent the1. ##,2. ##, etc.
In MDX documentation files, any content that belongs to a step must be indented with 3 spaces: paragraphs, bullets, images,<Tabs>,<TabItem>, and fenced code blocks
In MDX documentation files, prefer plain Markdown inside<Steps>. If the content is mostly<Tabs>or other JSX-heavy blocks, use normal section headings instead of<Steps>
In MDX documentation files, when<Tabs>is used inside a step, keep<Tabs>,<TabItem>,</TabItem>, and</Tabs>consistently nested under that step
In MDX documentation files, if a tabs block is not part of a numbered step, place it outside</Steps>
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
src/content/**/*.mdx
📄 CodeRabbit inference engine (CONTRIBUTING.md)
src/content/**/*.mdx: All documentation must live as MDX files insidesrc/content/
Every documentation page must have frontmatter with title (≤60 characters), description (≤160 characters), sidebar label, order, and tags
Write documentation in second person using 'you' and 'your application', present tense for descriptions, and imperative for step-by-step instructions
Avoid filler phrases like 'simply', 'just', 'easily' in documentation and be direct
Explain security implications when relevant in documentation
Every code block demonstrating an SDK operation must include all four languages (Node.js, Python, Go, Java) using synced tabs with syncKey='tech-stack'
SDK variable names are fixed and must not be renamed: Node.js usesscalekit, Python usesscalekit_client, Go usesscalekitClient, Java usesscalekitClient
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*.{md,mdx,astro,ts}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
**/*.{md,mdx,astro,ts}: Usepnpm pretty-quick --stagedvia pre-commit git hook to auto-format all staged.md,.mdx,.astro,.tsfiles with Prettier
Runpnpm formatto auto-format all.md,.mdx,.astro,.tsfiles before pushing changes
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
src/content/docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
src/content/docs/**/*.{md,mdx}: Every documentation page must include frontmatter withtitle,description, andsidebar.label;titlemust be at most 60 characters,descriptionat most 160 characters, and sidebar labels should be 1–3 words.
Use sentence case for all titles and headings, keep page titles short and descriptive, and make headings describe outcomes rather than categories.
Use H2 for major sections, H3 for subsections, H4 only inside<Steps>, and never use H1 in body content.
Use descriptive link text, prefer relative links for internal pages, and never use labels such asclick hereorthis.
Use fenced code blocks with language identifiers, format technical identifiers with inline code, include table headers, and ensure examples are runnable or clearly marked as placeholders.
Never hard-code secrets or API keys in documentation or code examples; explain relevant security threats and mitigations.
Documentation code examples must use the exact SDK variable names: Node.jsscalekit, Pythonscalekit_client, GoscalekitClient, and JavascalekitClient.
At least approximately 90% of SDK-related code examples must include Node.js, Python, Go, and Java implementations, with consistent naming, success and error paths, and security explanations.
Use<Tabs syncKey="tech-stack">for multi-language SDK samples and include clear language tabs, imports, realistic data, success and error handling, and appropriate Expressive Code features.
When using Starlight<Steps>, keep numbered steps at column 0, indent continuation content and sub-bullets by exactly three spaces, and keep nested<Tabs>blocks inside the owning list item.
Use the primary structure appropriate to each document type: how-to guides include overview, prerequisites, procedure, verification, and optional next steps; API references include endpoint summary, authentication, base URL, parameters, request, response, and errors; concept pages include overview, concepts, use cases, t...
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
src/**/*.{ts,tsx,astro,md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
Navigation structure changes must be coordinated across
src/configs/sidebar.config.ts,src/components/overrides/Header.astro, andsrc/components/SecondaryNav.astro.
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
src/content/docs/agentkit/**/*.{md,mdx}
📄 CodeRabbit inference engine (CLAUDE.md)
Before updating AgentKit snippets, consult the current implementation in the external
scalekit-developers/agent-auth-examplesrepository and verify that documentation snippets match it.
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*.{ts,tsx,astro,md,mdx,css}
📄 CodeRabbit inference engine (CLAUDE.md)
All changes must pass Prettier formatting, the build, Git hook validations, and content-structure validation; use pnpm, Astro/Starlight conventions, Tailwind CSS compatibility, and Vue 3 and React compatibility.
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*.{ts,tsx,astro,md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Use Astro + Starlight conventions, maintain Tailwind CSS compatibility, and ensure Vue 3 and React component compatibility.
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*
📄 CodeRabbit inference engine (AGENTS.md)
Use
pnpmfor package management, and ensure changes pass Prettier formatting, the build, Git hook validations, and content-structure validation.
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
**/*.{ts,tsx,js,jsx,java,py,go,md,mdx}
📄 CodeRabbit inference engine (AGENTS.md)
Use JSDoc, JavaDoc, or docstrings for functions, classes, and complex logic; document parameters, return values, types, exceptions, edge cases, useful references, and bug-fix issue links, using standard TODO, FIXME, and NOTE formats.
Files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
🧠 Learnings (15)
📚 Learning: 2026-01-30T18:18:50.883Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 415
File: src/content/docs/authenticate/fsa/multiapp/manage-apps.mdx:31-49
Timestamp: 2026-01-30T18:18:50.883Z
Learning: In all Scalekit documentation files (MDX), treat the terms 'Applications', 'Single Page Application (SPA)', 'Native Application', and 'Web Application' as proper nouns and preserve their capitalization in headings and body text. Ensure these terms remain capitalized even when used in sentence case or within prose.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-02-04T12:47:16.544Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 412
File: src/content/docs/dev-kit/tools/scalekit-dryrun.mdx:1-23
Timestamp: 2026-02-04T12:47:16.544Z
Learning: In scalekit-inc/developer-docs, the MDX frontmatter field order is required only when the sidebar configuration points to a directory (for auto-generation). If the sidebar.config.ts references a specific file path, the order field is not required. Apply this check to all MDX files under src/content/docs: if a file contributes to an auto-generated sidebar (directory path), ensure order is present; if it’s linked to a concrete file, order can be omitted. Use sidebar.config.ts to determine whether a given MDX file falls under directory-based vs file-specific sidebar references.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-02-25T08:57:12.201Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/quickstart.mdx:2-10
Timestamp: 2026-02-25T08:57:12.201Z
Learning: In Scalekit developer-docs (Astro Starlight), do not auto-suggest adding tableOfContents in frontmatter unless the user explicitly overrides the default behavior. The default enables tableOfContents with minHeadingLevel 2 and maxHeadingLevel 3. Only set tableOfContents when you want to customize heading levels or disable it entirely; otherwise omit it for other docs.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-02-25T13:04:27.491Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:9-17
Timestamp: 2026-02-25T13:04:27.491Z
Learning: Allow page-level CSS overrides in MDX frontmatter (head: style) for readability and engagement, even if it customizes typography beyond defaults. This applies to per-page UX decisions, including heading sizes and style tweaks, but keep overrides purposeful, accessible, and within the repository's design guidelines. Use these overrides sparingly and document the rationale for maintainability.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-03-05T11:29:08.125Z
Learnt from: AkshayParihar33
Repo: scalekit-inc/developer-docs PR: 463
File: src/content/docs/agent-auth/providers.mdx:35-73
Timestamp: 2026-03-05T11:29:08.125Z
Learning: In src/content/docs/agent-auth/providers.mdx, the Card components intentionally use icon=" " (a space) to render consistent colored boxes since some Starlight icon names resolve to icons and others do not. Do not flag icon=" " as a placeholder issue for this file; treat this as a deliberate UX choice specific to this MDX page and avoid raising a placeholder-icon warning here.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-03-09T07:27:56.794Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 469
File: src/content/docs/guides/integrations/scim-integrations/azure-scim.mdx:95-107
Timestamp: 2026-03-09T07:27:56.794Z
Learning: Do not enforce the 3-space indentation rule for Steps component content as a hard style rule in MDX files under src/content/docs/**/*.mdx. Only flag/rectify it if it causes visible rendering problems in the UI. Otherwise, allow current formatting; apply this rule only when rendering issues are observed and document any fixes.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-03-09T07:32:38.426Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 467
File: src/content/docs/sso/guides/sso-user-attributes.mdx:108-148
Timestamp: 2026-03-09T07:32:38.426Z
Learning: In MDX code samples under src/content/docs (and similar conceptual snippets in scalekit-inc/developer-docs), when an example's sole purpose is to show how to access a specific value (e.g., reading JWT claims after token validation), omit error/non-happy-path handling to keep the snippet focused. Do not flag the absence of error paths in narrowly scoped conceptual snippets.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-03-17T16:01:50.487Z
Learnt from: dhaneshbs
Repo: scalekit-inc/developer-docs PR: 506
File: src/content/docs/authenticate/fsa/quickstart.mdx:851-853
Timestamp: 2026-03-17T16:01:50.487Z
Learning: In the Scalekit Python SDK docs, clarify that LogoutUrlOptions is not exported from the top-level scalekit package __init__.py. The correct import path in code samples or reviews is: from scalekit.common.scalekit import LogoutUrlOptions. Do not flag this import path as incorrect in documentation or code reviews; ensure examples reflect the proper import path to avoid confusion for users.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-02-25T18:41:00.639Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 446
File: src/content/docs/authenticate/m2m/api-auth-quickstart.mdx:78-78
Timestamp: 2026-02-25T18:41:00.639Z
Learning: Preserve full URLs inside code comments in MDX code blocks (bash/python/js) when the URLs are part of copyable examples. Do not flag these in code examples. Use relative paths in prose and hyperlinks within MDX; only enforce relative paths for markdown prose links, not for URLs inside code comments.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (.mdx files), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag links for missing `target="_blank"` or `rel="noopener"` (avoid adding raw HTML anchors just to include those attributes), and keep the approach consistent with existing docs styling.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-04-27T07:13:48.244Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 628
File: src/content/docs/agentkit/tools/scalekit-optimized-tools.mdx:59-102
Timestamp: 2026-04-27T07:13:48.244Z
Learning: In AgentKit documentation MDX files, when showing Python `execute_tool` calls, treat `connection_name` as a supported argument (along with `tool_name`, `tool_input`, `identifier`, and `connected_account_id`). Do not flag `connection_name` as an invalid/unsupported parameter in these Python examples.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-06-12T09:43:05.227Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 745
File: src/content/docs/agentkit/authentication/troubleshooting.mdx:22-49
Timestamp: 2026-06-12T09:43:05.227Z
Learning: In this repo, for AgentKit documentation pages under `src/content/docs/agentkit/`, do NOT enforce the usual “four-language (Node.js, Python, Go, Java) SDK tabs” requirement. AgentKit pages should include only the Python and Node.js tabs; if Go and Java tabs are missing on these pages, do not flag it during review.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
📚 Learning: 2026-05-16T17:25:30.736Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 693
File: src/content/docs/authenticate/mcp/troubleshooting.mdx:170-170
Timestamp: 2026-05-16T17:25:30.736Z
Learning: In this repo’s documentation (MD/MDX), external links should be written using plain Markdown link syntax: `[text](url)`. Do not flag external links for missing `target="_blank"` or `rel="noopener"`, and avoid converting Markdown links into raw HTML `<a>` tags just to add those attributes, since that would be inconsistent with the established doc pattern.
Applied to files:
src/content/docs/agentkit/sdks/python/errors.mdxsrc/content/docs/agentkit/sdks/node/errors.mdx
| A failure during `scalekit.tools.executeTool` comes from one of two places, and the fix differs for each: | ||
|
|
||
| - **The upstream provider rejected the call** (Gmail, Slack, Salesforce, and so on). Scalekit raises a dedicated `ScalekitTool*` exception. The most common is `ScalekitToolUnauthorizedException`, which means the connected account's provider token was expired or revoked — re-authorize the connected account. Do not change your client credentials. | ||
| - **Scalekit rejected the call.** A plain `ScalekitUnauthorizedException` (no tool details) means your `client_id`/`client_secret` or Scalekit token is invalid. The SDK already refreshed and retried before surfacing it, so fix the credentials. | ||
|
|
||
| Each tool exception subclasses its plain counterpart — `ScalekitToolUnauthorizedException` extends `ScalekitUnauthorizedException` — so **catch the tool type first**. Use `isToolException()` to detect any upstream tool failure, and read `toolErrorCode`, `toolErrorMessage`, and `executionId` for logging. | ||
|
|
||
| ```ts wrap showLineNumbers=false | ||
| import { | ||
| ScalekitToolUnauthorizedException, | ||
| ScalekitToolRateLimitException, | ||
| ScalekitUnauthorizedException, | ||
| isToolException, | ||
| } from '@scalekit-sdk/node' | ||
|
|
||
| try { | ||
| const result = await scalekit.tools.executeTool({ | ||
| toolName: 'gmail_send_email', | ||
| identifier: 'user@example.com', | ||
| }) | ||
| } catch (err) { | ||
| if (err instanceof ScalekitToolUnauthorizedException) { | ||
| // Upstream provider rejected the token — re-authorize the connected account | ||
| } else if (err instanceof ScalekitToolRateLimitException) { | ||
| // Upstream provider rate limit — back off, then retry the tool call | ||
| } else if (err instanceof ScalekitUnauthorizedException) { | ||
| // Scalekit-side credentials are invalid — fix client ID/secret | ||
| } else if (isToolException(err)) { | ||
| // Any other upstream tool failure — inspect the provider's error code | ||
| console.error(err.toolErrorCode, err.executionId) | ||
| } else { | ||
| throw err | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| | Exception | When it is raised | Typical response | | ||
| | --- | --- | --- | | ||
| | `ScalekitToolUnauthorizedException` | Upstream provider returned 401 during tool execution | Re-authorize the connected account | | ||
| | `ScalekitToolForbiddenException` | Upstream provider returned 403 during tool execution | Add the missing provider scope, then re-authorize | | ||
| | `ScalekitToolRateLimitException` | Upstream provider returned 429 during tool execution | Back off and retry the tool call | | ||
| | `ScalekitToolException` | Any other upstream provider error during tool execution | Log `toolErrorCode` and `executionId`; surface a clear message | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
examples_dir="$(mktemp -d)"
trap 'rm -rf "$examples_dir"' EXIT
git clone --depth=1 https://github.com/scalekit-developers/agent-auth-examples.git "$examples_dir"
rg -n -C 4 \
'executeTool|execute_tool|isToolException|ScalekitTool[A-Za-z]+Exception|toolError(Code|Message)|tool_error_(code|message)|execution(Id|_id)|refresh|retry' \
"$examples_dir"Repository: scalekit-inc/developer-docs
Length of output: 23077
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- local documentation ---'
sed -n '1,140p' src/content/docs/agentkit/sdks/node/errors.mdx
sed -n '1,135p' src/content/docs/agentkit/sdks/python/errors.mdx
printf '%s\n' '--- local SDK and exception references ---'
rg -n -C 3 \
'ScalekitTool|isToolException|toolError(Code|Message)|tool_error_(code|message)|execution(Id|_id)|executeTool|execute_tool|tools\.execute|actions\.execute|refresh.*retry|retry.*refresh' \
--glob '!src/content/docs/agentkit/sdks/node/errors.mdx' \
--glob '!src/content/docs/agentkit/sdks/python/errors.mdx' .
printf '%s\n' '--- current AgentKit examples ---'
examples_dir="$(mktemp -d)"
trap 'rm -rf "$examples_dir"' EXIT
git clone --depth=1 https://github.com/scalekit-developers/agent-auth-examples.git "$examples_dir" >/dev/null
rg -n -C 5 \
'executeTool|execute_tool|isToolException|ScalekitTool[A-Za-z]+Exception|toolError(Code|Message)|tool_error_(code|message)|execution(Id|_id)|refresh|retry' \
"$examples_dir"Repository: scalekit-inc/developer-docs
Length of output: 50386
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- node errors page ---'
nl -ba src/content/docs/agentkit/sdks/node/errors.mdx | sed -n '50,115p'
printf '%s\n' '--- python errors page ---'
nl -ba src/content/docs/agentkit/sdks/python/errors.mdx | sed -n '48,110p'
printf '%s\n' '--- focused local AgentKit references ---'
rg -n -C 2 \
'ScalekitTool|isToolException|toolError(Code|Message)|tool_error_(code|message)|execution(Id|_id)|executeTool|execute_tool|actions\.execute|tools\.execute|refresh|retry' \
src/content/docs/agentkit src/components/templates/agent-connectors \
-g '*.mdx' -g '*.md' | head -n 500
printf '%s\n' '--- external example files and focused calls ---'
examples_dir="$(mktemp -d)"
trap 'rm -rf "$examples_dir"' EXIT
git clone --depth=1 https://github.com/scalekit-developers/agent-auth-examples.git "$examples_dir" >/dev/null
find "$examples_dir" -maxdepth 4 -type f | sort | sed -n '1,220p'
rg -n -C 4 \
'executeTool|execute_tool|ScalekitTool|isToolException|toolError|tool_error|executionId|execution_id|refresh|retry' \
"$examples_dir/javascript" "$examples_dir/python" | head -n 800
printf '%s\n' '--- repository package and lock references ---'
rg -n -C 2 \
'`@scalekit-sdk/node`|scalekit.*python|agentkit|ScalekitUnauthorizedException|ScalekitToolException' \
package.json pnpm-lock.yaml . \
-g 'package.json' -g 'pyproject.toml' -g 'requirements*.txt' -g 'pnpm-lock.yaml' \
-g '!src/content/**' -g '!src/components/**' 2>/dev/null | head -n 300Repository: scalekit-inc/developer-docs
Length of output: 230
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '%s\n' '--- node errors page ---'
sed -n '50,115p' src/content/docs/agentkit/sdks/node/errors.mdx | awk '{printf "%4d %s\n", NR+49, $0}'
printf '%s\n' '--- python errors page ---'
sed -n '48,110p' src/content/docs/agentkit/sdks/python/errors.mdx | awk '{printf "%4d %s\n", NR+47, $0}'
printf '%s\n' '--- focused local references ---'
rg -n -C 2 \
'ScalekitTool|isToolException|toolError(Code|Message)|tool_error_(code|message)|execution(Id|_id)|executeTool|execute_tool|actions\.execute|tools\.execute|refresh|retry' \
src/content/docs/agentkit src/components/templates/agent-connectors \
-g '*.mdx' -g '*.md' | head -n 500
printf '%s\n' '--- external example files ---'
examples_dir="$(mktemp -d)"
trap 'rm -rf "$examples_dir"' EXIT
git clone --depth=1 https://github.com/scalekit-developers/agent-auth-examples.git "$examples_dir" >/dev/null
find "$examples_dir" -maxdepth 4 -type f | sort | sed -n '1,220p'
printf '%s\n' '--- focused external calls ---'
rg -n -C 4 \
'executeTool|execute_tool|ScalekitTool|isToolException|toolError|tool_error|executionId|execution_id|refresh|retry' \
"$examples_dir/javascript" "$examples_dir/python" | head -n 800
printf '%s\n' '--- package references ---'
rg -n -C 2 \
'`@scalekit-sdk/node`|agentkit|ScalekitUnauthorizedException|ScalekitToolException' \
package.json pnpm-lock.yaml . \
-g 'package.json' -g 'pyproject.toml' -g 'requirements*.txt' -g 'pnpm-lock.yaml' \
-g '!src/content/**' -g '!src/components/**' 2>/dev/null | head -n 300Repository: scalekit-inc/developer-docs
Length of output: 50385
🏁 Script executed:
#!/bin/bash
set -euo pipefail
examples_dir="$(mktemp -d)"
work_dir="$(mktemp -d)"
trap 'rm -rf "$examples_dir" "$work_dir"' EXIT
git clone --depth=1 https://github.com/scalekit-developers/agent-auth-examples.git "$examples_dir" >/dev/null
printf '%s\n' '--- external package manifests ---'
find "$examples_dir" -maxdepth 3 -type f \( \
-name 'package.json' -o -name 'pyproject.toml' -o -name 'requirements*.txt' \
\) -print -exec sed -n '1,180p' {} \;
printf '%s\n' '--- external exception references ---'
rg -n -C 4 \
'ScalekitTool|ScalekitUnauthorized|isToolException|toolError|tool_error|executionId|execution_id|retry|refresh' \
"$examples_dir" \
-g '!*.lock' | head -n 500
printf '%s\n' '--- npm package metadata ---'
curl -fsSL https://registry.npmjs.org/@scalekit-sdk%2fnode \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print("latest:", d["dist-tags"].get("latest")); v=d["dist-tags"].get("latest"); print("tarball:", d["versions"][v]["dist"]["tarball"])'
npm_tarball="$(curl -fsSL https://registry.npmjs.org/@scalekit-sdk%2fnode \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["versions"][d["dist-tags"]["latest"]]["dist"]["tarball"])')"
curl -fsSL "$npm_tarball" -o "$work_dir/node.tgz"
mkdir "$work_dir/node"
tar -xzf "$work_dir/node.tgz" -C "$work_dir/node"
printf '%s\n' '--- npm exception and action source ---'
rg -n -C 5 \
'ScalekitTool|ScalekitUnauthorized|isToolException|toolError|executionId|executeTool|retry|refresh' \
"$work_dir/node" | head -n 1000
printf '%s\n' '--- PyPI package metadata candidates ---'
for package in scalekit scalekit-sdk; do
if curl -fsSL "https://pypi.org/pypi/$package/json" -o "$work_dir/$package.json"; then
python3 - "$work_dir/$package.json" "$package" <<'PY'
import json, sys
d=json.load(open(sys.argv[1]))
print(sys.argv[2], "latest:", d["info"]["version"])
print("tarball:", d["urls"][0]["url"])
PY
fi
doneRepository: scalekit-inc/developer-docs
Length of output: 50386
🏁 Script executed:
#!/bin/bash
set -euo pipefail
work_dir="$(mktemp -d)"
trap 'rm -rf "$work_dir"' EXIT
npm_tarball="$(curl -fsSL https://registry.npmjs.org/@scalekit-sdk%2fnode \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["versions"][d["dist-tags"]["latest"]]["dist"]["tarball"])')"
curl -fsSL "$npm_tarball" -o "$work_dir/node.tgz"
mkdir "$work_dir/node"
tar -xzf "$work_dir/node.tgz" -C "$work_dir/node"
printf '%s\n' '--- Node tool signatures ---'
sed -n '55,115p' "$work_dir/node/package/lib/tools.d.ts"
sed -n '55,105p' "$work_dir/node/package/lib/actions.d.ts"
printf '%s\n' '--- Node exception declarations ---'
sed -n '1,145p' "$work_dir/node/package/lib/errors/specific-exceptions.d.ts"
printf '%s\n' '--- Node exception implementation and retry references ---'
rg -n -C 5 \
'isToolException|isToolError|toolErrorCode|toolErrorMessage|executionId|ScalekitTool|retry|refresh|Unauthenticated|UNAUTHENTICATED' \
"$work_dir/node/package/lib/errors" \
"$work_dir/node/package/lib" \
-g '*.js' -g '*.d.ts' | head -n 1000
printf '%s\n' '--- Python package metadata ---'
curl -fsSL https://pypi.org/pypi/scalekit-sdk-python/json -o "$work_dir/python.json"
python3 - "$work_dir/python.json" <<'PY'
import json, sys
d = json.load(open(sys.argv[1]))
print("version:", d["info"]["version"])
for u in d["urls"]:
if u["packagetype"] == "sdist":
print("sdist:", u["url"])
PY
python_url="$(python3 - "$work_dir/python.json" <<'PY'
import json, sys
d = json.load(open(sys.argv[1]))
print(next(u["url"] for u in d["urls"] if u["packagetype"] == "sdist"))
PY
)"
curl -fsSL "$python_url" -o "$work_dir/python.tar.gz"
mkdir "$work_dir/python"
tar -xzf "$work_dir/python.tar.gz" -C "$work_dir/python"
printf '%s\n' '--- Python tool and exception references ---'
rg -n -C 5 \
'def execute_tool|ScalekitTool|ScalekitUnauthorized|tool_error_code|tool_error_message|execution_id|is_tool|retry|refresh' \
"$work_dir/python" | head -n 1200Repository: scalekit-inc/developer-docs
Length of output: 50384
🏁 Script executed:
#!/bin/bash
set -euo pipefail
work_dir="$(mktemp -d)"
trap 'rm -rf "$work_dir"' EXIT
npm_tarball="$(curl -fsSL https://registry.npmjs.org/@scalekit-sdk%2fnode \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(d["versions"][d["dist-tags"]["latest"]]["dist"]["tarball"])')"
curl -fsSL "$npm_tarball" -o "$work_dir/node.tgz"
mkdir "$work_dir/node"
tar -xzf "$work_dir/node.tgz" -C "$work_dir/node"
node_pkg="$work_dir/node/package"
printf '%s\n' '--- Node signatures and exception hierarchy ---'
sed -n '85,105p' "$node_pkg/lib/tools.d.ts"
sed -n '65,90p' "$node_pkg/lib/actions.d.ts"
sed -n '1,125p' "$node_pkg/lib/errors/specific-exceptions.d.ts"
rg -n -C 3 \
'function isToolException|isToolException\(|toolErrorCode|toolErrorMessage|executionId|class ScalekitTool' \
"$node_pkg/lib/errors" -g '*.js' -g '*.d.ts' | head -n 450
printf '%s\n' '--- Python signatures and exception hierarchy ---'
python_url="$(curl -fsSL https://pypi.org/pypi/scalekit-sdk-python/json \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(next(u["url"] for u in d["urls"] if u["packagetype"]=="sdist"))')"
curl -fsSL "$python_url" -o "$work_dir/python.tar.gz"
mkdir "$work_dir/python"
tar -xzf "$work_dir/python.tar.gz" -C "$work_dir/python"
python_root="$(find "$work_dir/python" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
rg -n -C 3 \
'def execute_tool|class ScalekitTool|class ScalekitUnauthorized|tool_error_code|tool_error_message|execution_id|TOOL_ERROR|__authenticate_client' \
"$python_root/scalekit/actions" "$python_root/scalekit/common/exceptions.py" \
"$python_root/scalekit/common/core.py" "$python_root/tests/test_sk819_retry_behavior.py" \
-g '*.py' | head -n 900
printf '%s\n' '--- gmail send tool input references ---'
rg -n -C 5 \
'gmail_send_email|send_email|toolInput|tool_input|params:' \
src/content/docs/agentkit "$node_pkg" \
-g '*.mdx' -g '*.md' -g '*.js' -g '*.d.ts' -g '*.py' | head -n 700Repository: scalekit-inc/developer-docs
Length of output: 50383
🏁 Script executed:
#!/bin/bash
set -euo pipefail
work_dir="$(mktemp -d)"
examples_dir="$(mktemp -d)"
trap 'rm -rf "$work_dir" "$examples_dir"' EXIT
python_url="$(curl -fsSL https://pypi.org/pypi/scalekit-sdk-python/json \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(next(u["url"] for u in d["urls"] if u["packagetype"]=="sdist"))')"
curl -fsSL "$python_url" -o "$work_dir/python.tar.gz"
mkdir "$work_dir/python"
tar -xzf "$work_dir/python.tar.gz" -C "$work_dir/python"
python_root="$(find "$work_dir/python" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
printf '%s\n' '--- Python execute_tool signature and client exposure ---'
sed -n '105,145p' "$python_root/scalekit/actions/actions.py"
rg -n -C 3 \
'class .*Tools|def execute_tool|self\.tools|tools =' \
"$python_root/scalekit" -g '*.py' | head -n 350
printf '%s\n' '--- Gmail send references in repository ---'
rg -n -C 6 \
'gmail_send_email|send_email' \
src/content/docs/agentkit src/components/templates/agent-connectors \
-g '*.mdx' -g '*.md' | head -n 500 || true
printf '%s\n' '--- Gmail send references in current external examples ---'
git clone --depth=1 https://github.com/scalekit-developers/agent-auth-examples.git "$examples_dir" >/dev/null
rg -n -C 6 \
'gmail_send_email|send_email' \
"$examples_dir" | head -n 500 || true
printf '%s\n' '--- reviewed code fence attributes ---'
rg -n \
'^```(ts|typescript|python)( |$)' \
src/content/docs/agentkit/sdks/node/errors.mdx \
src/content/docs/agentkit/sdks/python/errors.mdxRepository: scalekit-inc/developer-docs
Length of output: 32221
🏁 Script executed:
#!/bin/bash
set -euo pipefail
work_dir="$(mktemp -d)"
trap 'rm -rf "$work_dir"' EXIT
python_url="$(curl -fsSL https://pypi.org/pypi/scalekit-sdk-python/json \
| python3 -c 'import json,sys; d=json.load(sys.stdin); print(next(u["url"] for u in d["urls"] if u["packagetype"]=="sdist"))')"
curl -fsSL "$python_url" -o "$work_dir/python.tar.gz"
mkdir "$work_dir/python"
tar -xzf "$work_dir/python.tar.gz" -C "$work_dir/python"
python_root="$(find "$work_dir/python" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
printf '%s\n' '--- Python tools.execute_tool signature ---'
sed -n '88,135p' "$python_root/scalekit/tools.py"
printf '%s\n' '--- Python tools request construction ---'
sed -n '135,190p' "$python_root/scalekit/tools.py"
printf '%s\n' '--- Gmail input examples in documentation ---'
sed -n '88,103p' src/content/docs/agentkit/authentication/token-management.mdx
sed -n '324,334p' src/content/docs/agentkit/authentication/token-management.mdxRepository: scalekit-inc/developer-docs
Length of output: 2676
Make both error examples runnable and preserve full diagnostics.
- Pass
to,subject, andbodythroughparamsforgmail_send_email. - Log
toolErrorMessagewith the other diagnostic fields. - Add
titleattributes to both fenced code blocks.
📍 Affects 2 files
src/content/docs/agentkit/sdks/node/errors.mdx#L60-L101(this comment)src/content/docs/agentkit/sdks/python/errors.mdx#L58-L97
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/agentkit/sdks/node/errors.mdx` around lines 60 - 101, Update
both error examples in src/content/docs/agentkit/sdks/node/errors.mdx (lines
60-101) and src/content/docs/agentkit/sdks/python/errors.mdx (lines 58-97): make
each gmail_send_email call runnable by passing to, subject, and body through
params, add title attributes to both fenced code blocks, and include
toolErrorMessage alongside the existing diagnostic fields in logging. Ensure the
corresponding language-specific syntax remains valid.
Source: Path instructions
| Each tool exception subclasses its plain counterpart — `ScalekitToolUnauthorizedException` extends `ScalekitUnauthorizedException` — so **catch the tool type first**. Use `isToolException()` to detect any upstream tool failure, and read `toolErrorCode`, `toolErrorMessage`, and `executionId` for logging. | ||
|
|
||
| ```ts wrap showLineNumbers=false | ||
| import { | ||
| ScalekitToolUnauthorizedException, | ||
| ScalekitToolRateLimitException, | ||
| ScalekitUnauthorizedException, | ||
| isToolException, | ||
| } from '@scalekit-sdk/node' | ||
|
|
||
| try { | ||
| const result = await scalekit.tools.executeTool({ | ||
| toolName: 'gmail_send_email', | ||
| identifier: 'user@example.com', | ||
| }) | ||
| } catch (err) { | ||
| if (err instanceof ScalekitToolUnauthorizedException) { | ||
| // Upstream provider rejected the token — re-authorize the connected account | ||
| } else if (err instanceof ScalekitToolRateLimitException) { | ||
| // Upstream provider rate limit — back off, then retry the tool call | ||
| } else if (err instanceof ScalekitUnauthorizedException) { | ||
| // Scalekit-side credentials are invalid — fix client ID/secret | ||
| } else if (isToolException(err)) { | ||
| // Any other upstream tool failure — inspect the provider's error code | ||
| console.error(err.toolErrorCode, err.executionId) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- tracked candidate files ---'
git ls-files 'src/content/docs/agentkit/sdks/node/errors.mdx' \
'src/content/docs/agentkit/sdks/python/errors.mdx' \
'src/content/docs/agentkit/**' | sed -n '1,120p'
printf '%s\n' '--- node errors.mdx ---'
sed -n '1,130p' src/content/docs/agentkit/sdks/node/errors.mdx
printf '%s\n' '--- python errors.mdx ---'
sed -n '1,130p' src/content/docs/agentkit/sdks/python/errors.mdx
printf '%s\n' '--- repository references to the claimed fields ---'
rg -n --glob '!node_modules' \
'tool(ErrorMessage|_error_message)|toolErrorCode|tool_error_code|executionId|execution_id' \
src/content src README.md 2>/dev/null | sed -n '1,240p'
printf '%s\n' '--- external repository metadata ---'
curl -L --fail --silent --show-error \
https://api.github.com/repos/scalekit-developers/agent-auth-examples/contents \
| jq -r '.[] | [.type, .path, .download_url] | `@tsv`' | sed -n '1,160p'Repository: scalekit-inc/developer-docs
Length of output: 21010
🌐 Web query:
Search the public scalekit-developers/agent-auth-examplesrepository and current Scalekit AgentKit Node.js and Python SDK documentation forScalekitToolException, toolErrorMessage, tool_error_message, toolErrorCode, tool_error_code, executionId, and execution_id. Identify the current diagnostic fields and example logging behavior.
💡 Result:
In the Scalekit AgentKit ecosystem, diagnostic fields and error handling are managed through a specific hierarchy of exceptions and identifiers. Diagnostic Fields and Identifiers Execution IDs are consistently represented as executionId (typically CamelCase in Node.js/TypeScript SDKs and related metadata) [1][2][3][4]. While execution_id is sometimes used in YAML-based configurations or frontmatter [1][2][5], the SDK interfaces primarily expose executionId. Error Handling and Diagnostic Exceptions Scalekit uses a typed exception hierarchy to handle tool execution failures, centralizing diagnostics through ScalekitToolException [6]. This exception hierarchy allows for granular error handling: 1. ScalekitToolRateLimitException: Specifically handles provider 429 errors [6]. 2. ScalekitToolUnauthorizedException: Specifically handles provider 401 errors [6]. 3. ScalekitToolForbiddenException: Specifically handles provider 403 errors [6]. 4. ScalekitToolException: The base class for other provider errors, extending ScalekitServerException [6]. These exceptions facilitate diagnostic logging by allowing developers to differentiate between provider-level issues and general API failures. The isToolException(e) type guard is available to catch all provider-related errors collectively [6]. Logging and Diagnostic Behavior Diagnostic information is accessed through both explicit SDK methods and dashboard logs: - SDK Diagnostics: For tool execution, logs generally surface through the result of scalekit.actions.executeTool [7]. If a tool call fails, the error message often points to scopes, credentials, or provider rate limits [7]. - Dashboard Logs: The Scalekit dashboard provides a centralized view for monitoring, where users can review connected account status, refresh history, and tool execution logs [7]. - Behavior Note: A key recent change in Scalekit SDK behavior is that provider errors (including 429s) are no longer retried automatically by the SDK; they surface immediately to allow the caller to manage their own retry strategy [6]. Note: While queries for toolErrorMessage, tool_error_message, toolErrorCode, and tool_error_code were performed, these fields do not appear as standard, first-class diagnostic properties within the official Scalekit AgentKit SDK interfaces; rather, diagnostic details are extracted from the structured exception hierarchy or the return data of execution methods [6][7].
Citations:
- 1: https://github.com/webpresso/agent-kit/blob/main/src/blueprint/execution/metadata.ts
- 2: https://github.com/webpresso/agent-kit/blob/main/src/blueprint/execution/types.ts
- 3: https://github.com/sapiom/sapiom-js/blob/main/packages/agent-core/src/run.ts
- 4: https://github.com/sapiom/sapiom-js/blob/main/packages/agent-runtime/src/runner-core.ts
- 5: https://github.com/webpresso/agent-kit/blob/main/src/blueprint/execution/metadata.test.ts
- 6: fix(SK-819, SK-821): provider error differentiation, blind retry fix, and upsert credentials scalekit-sdk-node#200
- 7: https://docs.scalekit.com/agentkit/authentication/troubleshooting/
🌐 Web query:
Open and summarize https://github.com/scalekit-inc/scalekit-sdk-node/pull/200 and the current scalekit-inc/scalekit-sdk-nodesource. Focus on the definitions ofScalekitToolException, ScalekitToolUnauthorizedException, isToolException, toolErrorCode, toolErrorMessage, and executionId, including whether these properties are public and intended for logging.
💡 Result:
The scalekit-sdk-node library introduced a new exception hierarchy for tool execution errors in Pull Request #200 [1]. These additions are designed to improve error differentiation, specifically separating errors originating from upstream providers from those caused by Scalekit itself [1]. Definitions and usage: - ScalekitToolException: The base exception class for provider-side errors, extending ScalekitServerException [1]. It represents generic provider errors that occur during tool execution [1]. - ScalekitToolUnauthorizedException: A specific subclass of ScalekitUnauthorizedException, triggered when an upstream provider returns a 401 status [1]. Unlike general authentication failures, this surfaces immediately without automatic token refresh attempts [1]. - isToolException(e): A type guard function used to identify if an error is a provider-side "tool error" [1][2]. It allows developers to check for these specific errors in a single catch block, which is essential for distinguishing provider rate limits or auth issues from Scalekit's own platform errors [1][3]. - toolErrorCode and toolErrorMessage: These properties are associated with the underlying error details [1][3]. The SDK extracts these from the response when a tool execution fails [1][2]. They are intended for developers to inspect the nature of the provider error (e.g., identifying if a 429 was caused by a TOOL_ERROR or a platform RATE_LIMITED issue) to implement correct backoff strategies [3]. - executionId: While not explicitly defined as a top-level property of the exception classes in the summary of PR #200, execution-related information is typically surfaced through the error details and the broader Scalekit logging/audit infrastructure to help track tool-calling flows [1][4]. Regarding logging and publicity, these exception properties are public, typed, and intended for developer consumption in error-handling blocks [1][5][3]. They provide the necessary context to debug why a tool call failed—whether due to provider-side permissions, rate limits, or connectivity—making them suitable for structured logging in applications that manage agent tool calls [3][4]. Developers are encouraged to use these typed exceptions instead of parsing raw error strings to ensure robust and backward-compatible error handling [1][5].
Citations:
- 1: fix(SK-819, SK-821): provider error differentiation, blind retry fix, and upsert credentials scalekit-sdk-node#200
- 2: scalekit-inc/scalekit-sdk-node@a96e36a
- 3: https://docs.scalekit.com/reference/rate-limits/
- 4: https://docs.scalekit.com/agentkit/authentication/troubleshooting/
- 5: https://github.com/scalekit-inc/scalekit-sdk-node/blob/7a0503424cafd1ef3ae65a6845577b6dd6bb515c/REFERENCE.md
🌐 Web query:
Search the public Scalekit Python SDK source and documentation for ScalekitToolException, ScalekitToolUnauthorizedException, tool_error_code, tool_error_message, and execution_id. Determine which properties exist on the exceptions and how current examples handle them.
💡 Result:
In the Scalekit Python SDK, ScalekitToolException and ScalekitToolUnauthorizedException are part of an exception hierarchy designed to handle tool execution failures [1]. While these specific classes are prominently featured in the Node.js SDK's recent architectural updates [1], they reflect the underlying error structure used across Scalekit's platforms [2]. Properties such as tool_error_code, tool_error_message, and execution_id originate from the Scalekit API's tool execution response structure [2][3]. When a tool execution fails, these fields are typically provided within the error context [2]. Key findings regarding these properties and exceptions: 1. Exception Hierarchy: Scalekit uses a typed exception hierarchy to handle tool errors, where ScalekitToolUnauthorizedException typically extends an unauthorized base exception, and ScalekitToolException covers general provider-side errors [1]. These exceptions allow for granular error differentiation—such as distinguishing between a provider-side rate limit and a general execution failure—enabling more precise retry and recovery strategies [4][1]. 2. Error Properties: The fields tool_error_code, tool_error_message, and execution_id are standard components returned by the Scalekit API when a tool call fails [2]. - execution_id: A unique identifier for the specific tool execution attempt, useful for tracing and debugging [2][3]. - tool_error_code: A machine-readable code (e.g., TOOL_ERROR) identifying the specific nature of the failure [4][2]. - tool_error_message: A human-readable description of the error [4][2]. 3. Handling in SDKs: Current SDK implementations emphasize extracting these details to avoid blind retries [1]. For example, in rate-limiting scenarios, SDK users can inspect the error code to decide whether to apply provider-specific backoff or general request frequency reduction [4]. When building integrations, developers should check for these fields within exception objects to provide actionable feedback, such as clarifying input schema requirements when a field-level validation error occurs [5][2].
Citations:
- 1: fix(SK-819, SK-821): provider error differentiation, blind retry fix, and upsert credentials scalekit-sdk-node#200
- 2: https://docs.scalekit.com/saaskit/apis/
- 3: https://raw.githubusercontent.com/api-evangelist/scalekit/refs/heads/main/openapi/scalekit-connected-accounts-api-openapi.yml
- 4: https://docs.scalekit.com/reference/rate-limits/
- 5: Improve execute_tool errors for mismatched tool input key casing scalekit-sdk-python#151
🏁 Script executed:
#!/bin/bash
set -eu
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
printf '%s\n' '--- Node SDK PR patch references ---'
curl -L --fail --silent --show-error \
https://github.com/scalekit-inc/scalekit-sdk-node/pull/200.patch \
-o "$tmpdir/node.patch"
rg -n -C 5 \
'ScalekitToolException|ScalekitToolUnauthorizedException|isToolException|toolErrorCode|toolErrorMessage|executionId' \
"$tmpdir/node.patch" | sed -n '1,260p'
printf '%s\n' '--- Node SDK commit tree candidates ---'
curl -L --fail --silent --show-error \
https://github.com/scalekit-inc/scalekit-sdk-node/commit/a96e36a4f6722d16c56bffec5e9827843a62ceab.patch \
-o "$tmpdir/node-commit.patch"
rg -n -C 5 \
'ScalekitToolException|ScalekitToolUnauthorizedException|isToolException|toolErrorCode|toolErrorMessage|executionId' \
"$tmpdir/node-commit.patch" | sed -n '1,260p'
printf '%s\n' '--- Python SDK public repository refs ---'
git ls-remote https://github.com/scalekit-inc/scalekit-sdk-python.git \
'refs/heads/*' 'refs/tags/*' | sed -n '1,80p'
printf '%s\n' '--- Agent examples repository refs ---'
git ls-remote https://github.com/scalekit-developers/agent-auth-examples.git \
'refs/heads/*' 'refs/tags/*' | sed -n '1,80p'Repository: scalekit-inc/developer-docs
Length of output: 19007
🏁 Script executed:
#!/bin/bash
set -eu
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -L --fail --silent --show-error \
https://codeload.github.com/scalekit-inc/scalekit-sdk-python/tar.gz/1f635128c04374ec82a1088469c20182dbcec457 \
-o "$tmpdir/python.tgz"
mkdir "$tmpdir/python"
tar -xzf "$tmpdir/python.tgz" -C "$tmpdir/python"
printf '%s\n' '--- Python exception source paths ---'
find "$tmpdir/python" -type f | rg '/(exception|exceptions|error|errors)(/|\.|$)' | sed -n '1,120p'
printf '%s\n' '--- Python exception field definitions and usage ---'
rg -n -C 5 \
'ScalekitToolException|ScalekitToolUnauthorizedException|tool_error_code|tool_error_message|execution_id' \
"$tmpdir/python" | sed -n '1,320p'
curl -L --fail --silent --show-error \
https://codeload.github.com/scalekit-developers/agent-auth-examples/tar.gz/f1723f3ae184acac816dfed79a2429bdd07d1acd \
-o "$tmpdir/examples.tgz"
mkdir "$tmpdir/examples"
tar -xzf "$tmpdir/examples.tgz" -C "$tmpdir/examples"
printf '%s\n' '--- AgentKit example error-handling paths ---'
rg -n -C 5 \
'ScalekitToolException|ScalekitToolUnauthorizedException|tool(ErrorCode|ErrorMessage)|tool_(error_code|error_message)|execution(Id|_id)|isToolException' \
"$tmpdir/examples" | sed -n '1,320p'Repository: scalekit-inc/developer-docs
Length of output: 50383
🏁 Script executed:
#!/bin/bash
set -eu
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -L --fail --silent --show-error \
https://codeload.github.com/scalekit-developers/agent-auth-examples/tar.gz/f1723f3ae184acac816dfed79a2429bdd07d1acd \
-o "$tmpdir/examples.tgz"
mkdir "$tmpdir/examples"
tar -xzf "$tmpdir/examples.tgz" -C "$tmpdir/examples"
printf '%s\n' '--- external example files containing tool error handling ---'
rg -l \
'ScalekitToolException|ScalekitToolUnauthorizedException|tool(ErrorCode|ErrorMessage)|tool_(error_code|error_message)|isToolException' \
"$tmpdir/examples" | sed -n '1,120p'
printf '%s\n' '--- external example diagnostic lines ---'
rg -n \
'ScalekitToolException|ScalekitToolUnauthorizedException|tool(ErrorCode|ErrorMessage)|tool_(error_code|error_message)|execution(Id|_id)|isToolException' \
"$tmpdir/examples" | sed -n '1,180p'
printf '%s\n' '--- concise Python SDK definition ---'
curl -L --fail --silent --show-error \
https://raw.githubusercontent.com/scalekit-inc/scalekit-sdk-python/1f635128c04374ec82a1088469c20182dbcec457/scalekit/common/exceptions.py \
| sed -n '293,325p'
printf '%s\n' '--- documentation invariant check ---'
python3 - <<'PY'
from pathlib import Path
cases = {
Path("src/content/docs/agentkit/sdks/node/errors.mdx"): (
"toolErrorCode", "toolErrorMessage", "executionId",
"console.error(err.toolErrorCode, err.executionId)",
),
Path("src/content/docs/agentkit/sdks/python/errors.mdx"): (
"tool_error_code", "tool_error_message", "execution_id",
"print(e.tool_error_code, e.execution_id)",
),
}
for path, (code, message, execution, log_line) in cases.items():
text = path.read_text()
assert code in text and message in text and execution in text
assert log_line in text
print(f"{path}: documented={code,message,execution}; current_log_omits_message=True")
PYRepository: scalekit-inc/developer-docs
Length of output: 2023
Log the provider error message.
Both examples document the provider message field but log only the error code and execution ID. Include err.toolErrorMessage and e.tool_error_message in the diagnostic output.
📍 Affects 2 files
src/content/docs/agentkit/sdks/node/errors.mdx#L65-L89(this comment)src/content/docs/agentkit/sdks/python/errors.mdx#L63-L89
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/agentkit/sdks/node/errors.mdx` around lines 65 - 89, Update
the diagnostic logging in the Node example’s isToolException() branch to include
err.toolErrorMessage alongside toolErrorCode and executionId. Also update the
Python example at src/content/docs/agentkit/sdks/python/errors.mdx lines 63-89
to include e.tool_error_message alongside the existing provider error fields.
| ```ts wrap showLineNumbers=false | ||
| import { | ||
| ScalekitToolUnauthorizedException, | ||
| ScalekitToolRateLimitException, | ||
| ScalekitUnauthorizedException, | ||
| isToolException, | ||
| } from '@scalekit-sdk/node' | ||
|
|
||
| try { | ||
| const result = await scalekit.tools.executeTool({ | ||
| toolName: 'gmail_send_email', | ||
| identifier: 'user@example.com', | ||
| }) | ||
| } catch (err) { | ||
| if (err instanceof ScalekitToolUnauthorizedException) { | ||
| // Upstream provider rejected the token — re-authorize the connected account | ||
| } else if (err instanceof ScalekitToolRateLimitException) { | ||
| // Upstream provider rate limit — back off, then retry the tool call | ||
| } else if (err instanceof ScalekitUnauthorizedException) { | ||
| // Scalekit-side credentials are invalid — fix client ID/secret | ||
| } else if (isToolException(err)) { | ||
| // Any other upstream tool failure — inspect the provider's error code | ||
| console.error(err.toolErrorCode, err.executionId) | ||
| } else { | ||
| throw err | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -u
for file in \
src/content/docs/agentkit/sdks/node/errors.mdx \
src/content/docs/agentkit/sdks/python/errors.mdx
do
echo "===== $file ====="
sed -n '1,125p' "$file"
done
echo "===== AgentKit references ====="
rg -n --hidden -S \
'toolErrorMessage|tool_error_message|ScalekitToolUnauthorizedException|ScalekitToolRateLimitException|isToolException|<Code|from .+Code' \
src/content/docs/agentkit \
2>/dev/null || true
echo "===== Repository files related to AgentKit examples ====="
git ls-files | rg -i 'agent.?auth|agentkit|errors\.mdx' | head -200Repository: scalekit-inc/developer-docs
Length of output: 23984
🏁 Script executed:
#!/bin/bash
set -u
echo "===== Local <Code> conventions ====="
rg -n -U '<Code[\s\S]{0,250}(title=|lang=)|import \{? ?Code|from .+Code' src/content/docs src/components | head -200
echo "===== External AgentKit example repository ====="
curl -fsSL \
https://api.github.com/repos/scalekit-developers/agent-auth-examples/git/trees/main?recursive=1 \
| jq -r '.tree[]?.path' \
| rg -i 'error|exception|agentkit|node|python' \
| head -200
echo "===== External repository metadata ====="
curl -fsSL https://api.github.com/repos/scalekit-developers/agent-auth-examples \
| jq -r '{default_branch, html_url, archived}'Repository: scalekit-inc/developer-docs
Length of output: 5770
🌐 Web query:
site:github.com/scalekit-developers/agent-auth-examples AgentKit errors ScalekitToolUnauthorizedException
💡 Result:
There is no official record of an error named ScalekitToolUnauthorizedException in the Scalekit AgentKit documentation or associated repositories [1][2][3][4]. Errors related to unauthorized access in AgentKit generally manifest as standard HTTP 401 Unauthorized responses or specific diagnostic messages when a connector or connected account is not properly authorized [5][6][7]. If you encounter authorization issues while using AgentKit, consider the following troubleshooting steps: 1. Check Authorization Status: AgentKit flows typically print an authorization link in the logs if a user has not yet authorized access [1]. Follow this link to complete the OAuth flow [1][7]. 2. Verify Connected Accounts: Ensure that the specific connected account (the per-user instance of a connection) has been created and is in an active state in the Scalekit Dashboard [2]. 3. Validate Token Lifecycle: Scalekit handles OAuth token storage and automatic refresh [1][2]. If you are manually handling credentials, ensure that your tokens are not expired and that your application logic correctly handles the 401 Unauthorized response by triggering a re-authorization or refresh flow [5][6]. 4. Check Connector Configuration: Ensure that the credentials (such as API keys or OAuth client details) stored in your Scalekit connection configuration are valid and have the necessary scopes to perform the requested tool actions [2][5]. If you are seeing a specific exception name in your code that is not listed in the official documentation, it is possible that it is a custom exception class implemented within your specific application or a wrapper library rather than a core AgentKit SDK exception [8][4]. Check your local codebase for the definition of this exception to determine where it is being raised.
Citations:
- 1: https://github.com/scalekit-developers/agent-auth-examples
- 2: https://docs.scalekit.com/agentkit/overview/
- 3: https://docs.scalekit.com/_llms-txt/agentkit.txt
- 4: https://www.scalekit.com/agentkit
- 5: https://github.com/scalekit-developers/workflow-agents-demos/blob/main/langchain-crewai-mcp/README.md
- 6: Secure token Agent scalekit-developers/workflow-agents-demos#2
- 7: https://github.com/scalekit-developers/workflow-agents-demos/blob/main/deal-room-sync-agent/README.md
- 8: https://docs.scalekit.com/agentkit/sdks/
🌐 Web query:
"ScalekitToolUnauthorizedException" "agent-auth-examples"
💡 Result:
The ScalekitToolUnauthorizedException is a specific typed exception in the Scalekit SDK that indicates a 401 Unauthorized error occurred during a tool execution, typically originating from the third-party provider being accessed (e.g., Gmail, Slack, Notion) [1]. This exception is part of an error hierarchy designed to distinguish between SDK-level issues and provider-specific failures [1]. Unlike general authentication errors that might trigger an automatic token refresh, a ScalekitToolUnauthorizedException signifies that the provider itself has rejected the request, often due to an invalid, expired, or revoked access token, and it is raised immediately to prevent unnecessary retry amplification [1]. The agent-auth-examples repository (available at github.com/scalekit-developers/agent-auth-examples) serves as the official source for examples demonstrating how to use Scalekit’s authentication lifecycle [2][3]. These examples showcase how to: 1. Manage the OAuth flow (authorization, token storage, and automatic refresh) so agents can act on behalf of users [2][4]. 2. Use connected accounts to handle authentication consistently across different providers [4]. 3. Implement error handling patterns to catch typed exceptions, including those related to tool execution [5][6][7]. When encountering a ScalekitToolUnauthorizedException, it is recommended to: - Verify the connected account status using get_connected_account [8]. - Refresh the connected account credentials if necessary using refresh_connected_account [8]. - Ensure the scopes required by the tool match the scopes granted during the user's initial authorization flow [8].
Citations:
- 1: fix(SK-819, SK-821): provider error differentiation, blind retry fix, and upsert credentials scalekit-sdk-node#200
- 2: https://github.com/scalekit-developers/agent-auth-examples
- 3: https://docs.scalekit.com/agentkit/code-samples/
- 4: https://dev.to/saif_shines/multi-connector-oauth-meeting-scheduler-agent-using-google-calendar-gmail-scalekit-89e
- 5: https://docs.scalekit.com/agentkit/sdks/node.md
- 6: https://docs.scalekit.com/agentkit/sdks/node/errors/
- 7: https://docs.scalekit.com/agentkit/sdks/python/errors/
- 8: https://docs.scalekit.com/agent-auth/authentication/troubleshooting
🌐 Web query:
site:github.com/scalekit-developers/agent-auth-examples "execute_tool" "tool_error_code"
💡 Result:
No indexed GitHub results were found for:
site:github.com/scalekit-developers/agent-auth-examples "execute_tool" "tool_error_code"
The repository or those exact terms may not be publicly indexed.
Use titled <Code> samples
Import Code once in each file and replace the untitled fenced samples with <Code> components. Set each title to the example file path.
src/content/docs/agentkit/sdks/node/errors.mdx:67-94src/content/docs/agentkit/sdks/python/errors.mdx:65-90
📍 Affects 2 files
src/content/docs/agentkit/sdks/node/errors.mdx#L67-L94(this comment)src/content/docs/agentkit/sdks/python/errors.mdx#L65-L90
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/content/docs/agentkit/sdks/node/errors.mdx` around lines 67 - 94, Import
the Code component once in src/content/docs/agentkit/sdks/node/errors.mdx and
replace the untitled fenced sample around lines 67-94 with Code, setting its
title to the example file path. Apply the same change in
src/content/docs/agentkit/sdks/python/errors.mdx around lines 65-90, using that
sample’s example file path as the title.
Sources: Coding guidelines, Path instructions
2 participants
Why: A developer asked how to tell, in code, whether a failing AgentKit tool call means the upstream provider rejected the connected account's token (needs re-authorization) or their own Scalekit credentials are wrong. The error-handling reference only listed the base exceptions and described
ScalekitUnauthorizedExceptionas "fix client ID/secret," which conflates the two cases.What: Surgical addition of a "Tool execution errors" section to the Node and Python AgentKit error-handling pages. It documents the shipped tool-exception hierarchy —
ScalekitToolUnauthorizedException,ScalekitToolForbiddenException,ScalekitToolRateLimitException,ScalekitToolException— that Scalekit raises when the upstream provider rejects anexecuteTool/execute_toolcall. It explains that a tool 401 means re-authorize the connected account, while a plainScalekitUnauthorizedExceptionmeans fix client credentials, and shows how to readtoolErrorCode/executionId(NodeisToolException(); Python catches theScalekitToolExceptionbase). Verified against@scalekit-sdk/nodev2.11.0 andscalekit-sdk-pythonsource; Go and Java SDKs do not yet ship this hierarchy, so their pages are unchanged. Skills applied: docs-engineering, docs-contribution-router, scalekit-code-doctor, docs-writing-style.Check: Open the two preview links below; confirm a new "Tool execution errors" section appears after "Exception types" with the upstream-vs-Scalekit distinction and the tool-exception table.
Preview:
🤖 Generated with Claude Code
Summary by CodeRabbit