Tool Errors and Troubleshooting
Connector tool calls return a structured JSON error envelope designed so the AI can understand what went wrong, relay it in plain language, and offer sensible next steps. Platform tools,…
Written By Christopher Scaminaci
Last updated 3 days ago
Connector tool calls return a structured JSON error envelope designed so the AI can understand what went wrong, relay it in plain language, and offer sensible next steps. Platform tools, parameter-binding or protocol failures, and transport authorization failures can return smaller JSON shapes or an HTTP/MCP-level error instead. This page documents the representative cross-cutting errors that can affect many tools; each generated tool description remains the source of truth for operation-specific validation and state errors.
The error envelope
The full connector-execution envelope is shaped like this (fields that do not apply are omitted):
{
"error": true,
"errorType": "forbidden",
"retryable": false,
"tool": "halo_create_ticket",
"message": "Halo API returned 403 for /api/Tickets",
"guidance": "Access denied. The connector account may lack required permissions for this operation.",
"httpStatus": 403,
"upstreamError": "…the vendor API's own error body…",
"correlationId": "4bf92f3577b34da6a3ce929d0e0e4736",
"supportTicketDraft": { "subject": "…", "description": "…" },
"nextActions": [
{
"tool": "stackjack_create_support_ticket",
"requiresUserAuthorization": true,
"reason": "Ask the user before opening a StackJack support ticket with this draft."
}
]
}
Gate errors raised inside the same connector-execution path (plan, billing, allowance) carry this envelope without the upstream fields — for example a monthly_limit_exceeded message includes usage, limit, and the billing-cycle window (start–end), but no httpStatus or upstreamError.
Field by field:
On the shared connector-execution path, calls StackJack records as failed do not count against your monthly allowance. Only successful live connector calls consume quota; a successful replay served from a recorded fixture does not consume live connector quota either.
When a support draft appears
The current 14 support-worthy codes are authentication_error, authorization_expired, capability_not_enabled, connector_api_error, connector_not_configured, forbidden, gateway_timeout, internal_error, network_error, refresh_in_progress, refresh_token_persistence_failed, service_unavailable, timeout, and upstream_server_error.
No automatic draft is attached to bad_request, not_found, rate_limited, write_unverified (a HaloPSA read-back verdict; the cause is the vendor's own configuration, not a StackJack fault), cipp_result_failed (CIPP reported the failure inside its own response; the cause is inside your M365 tenant), connector_disconnected (your own organization removed the connection; reconnect it on the Connectors page), request_shape_error (the vendor could not read a field of the request your AI sent, so the AI corrects that field and sends the request again), user_context_required (NinjaOne needs this action done by a signed-in technician, and your NinjaOne connection is Client Credentials; switch it to Authorization Code on the Connectors page), connector_address_error (the connection's address reaches PRTG's classic web interface, which never read your key; point the connection at the PRTG Application Server), ordinary validation failures, or normal plan, permission-selection, subscription, billing, and allowance gates. If you elect to create a ticket from an eligible draft, the ticket is saved first and StackJack then attempts a system bundle and sanitized MCP-log upload independently. Those uploads are best-effort; the create response reports diagnosticsAttached, and the ticket remains open even if both uploads fail.
Retrying a failed or timed-out write
A write that failed or timed out may already have changed the upstream system. StackJack reports what it observed, and a connection that dropped after the vendor accepted the request looks the same from here as one that never arrived. Before you repeat a write, verify its outcome in the vendor — unless that operation's own documented idempotency contract makes a repeat safe.
This applies to every one of these:
Reads are different, but not free. Repeating a read does not change anything in the vendor, so the retry rule above does not apply. It does consume another call against the connector's monthly allowance, and it hands the returned records to your AI application again — which matters when the tool reads passwords, contacts, or other sensitive records.
A vendor error is not proof of a mistake on your side. bad_request and forbidden usually point at your request or your key's scope, but an unfamiliar vendor error can also come from a StackJack defect, a vendor incident, or a change in the vendor's API. Keep the correlationId and escalate rather than assuming the cause; see Troubleshooting recipes.
Error types: access and billing gates
These are raised by StackJack before the vendor API is ever contacted:
Error types: upstream vendor API failures
When your connected product's API rejects or fails a call, StackJack classifies the HTTP status:
A note on 404 and 429 semantics: a single wrong ID or a busy vendor API is an expected environmental outcome, so either code is not automatically a StackJack incident. Persistent 404s for known-valid IDs or sustained 429s after backoff can still signal an endpoint, entitlement, permission, pacing, or vendor-service problem and are worth escalating with correlation ids. The other 4xx codes (401/403) usually point at credential or permission configuration and need action.
Error types: credentials and configuration
Error types: everything else
Oversized results: the spilled-result envelope
Some calls succeed and return more data than can be sent back through the AI connection in one piece — a full ticket export, a year of device telemetry. A single tool result may carry at most 5,000,000 characters (about 5 MB of text), or the lower ceiling an Automation sets for itself. A result is never silently truncated: rather than throw that data away, StackJack saves the complete result and hands your AI a link to it:
{
"spilled": true,
"tool": "halo_list_tickets",
"chars": 6115797,
"url": "https://…",
"expiresAt": "2026-09-07T03:04:05+00:00",
"preview": "{\"tickets\":[{\"id\":48213,…",
"guidance": "The full result is at url (valid until expiresAt). Fetch it with your file/URL tool; do not ask for it again through this tool."
}
What to know:
- This is a success, not an error. There is no
errororerrorTypefield. The vendor call happened, the data is complete, and the call counts toward the connector's monthly allowance like any other successful call. charsis the size of the full result, not of the preview. Use it to decide whether fetching is worth it or whether to narrow the request instead.previewis the first 2,000 characters of the real result. It is there so the AI can see the shape of the data — never report it to a user as the whole answer.urlis a temporary read link, andexpiresAtis the only authority on how long it lasts. Read the expiry out of the response rather than assuming a duration; it is set when the link is minted and varies with how StackJack's storage is configured. Fetch the link with a tool that can read a URL or download a file, and fetch it beforeexpiresAt. Repeating the original tool call re-runs the vendor query and produces a new link, which is slower and consumes another call.- Only successful results are saved this way. Error responses are always returned in full as the normal error envelope.
- Known secret-returning tools are excluded from this storage. StackJack keeps a reviewed list of the tools whose job is to return secrets: stored passwords, API keys, vault entries. Their responses are handed straight to your AI and are never written to storage, even temporarily. If one of them exceeds the cap it comes back as
tool_result_too_largeinstead of a link. Narrow the request (a single record, a smaller page size, one folder at a time) and it returns inline as normal. A tool whose answer only carries a secret as one field inside a larger record is different: StackJack removes that field, and the rest of the answer can be stored (see Secrets inside tool answers). StackJack also reads the answer itself: a field named like a credential (a password, secret, token or key) that has a value keeps the answer out of storage too. That check goes by field names, not by recognizing a secret value, so a sensitive value under an ordinary field name is not detected and can be written to the temporary link. Treat the link as carrying whatever the vendor returned, and keep the tool selection narrow for connectors holding sensitive records.
If the result cannot be saved, an oversized result returns tool_result_too_large instead — narrow the request with filters, fewer fields, or a smaller page size and iterate over pages.
Asking for a link for a smaller result
A result under the cap can come back as the same link envelope too, so a large listing does not fill your AI assistant's context:
- For one call: pass
"resultAsLink": truetostackjack_run_toolorstackjack_run_readonly_tool. The result comes back as a link whatever its size. - For your organization: an owner or administrator turns on Large tool results on the Settings page and chooses a size between 50,000 and 5,000,000 characters. Every successful tool result larger than that size then comes back as a link on your AI assistants' connections. An Automation's own connection is not affected, because its agent may not be able to download a link.
Everything above still applies to these links. One thing differs: a result under the cap that cannot be saved as a link (a tool that returns secrets, or a link that could not be created) comes back in the conversation as normal, never as tool_result_too_large. When the call asked for the link with resultAsLink, the result's _meta carries a stackjack.resultLink note that says why it came back in the conversation instead (reason is one of secret_response, secret_in_request, credential_tool, credential_in_result, link_unavailable or error_result, the last for an error, which is never stored as a link). Some AI clients do not show _meta to the model.
Secrets inside tool answers
Some tools answer with a record that is useful on its own but carries one secret field inside it. StackJack leaves that field out of the answer unless you ask for it:
- By default the secret field is removed. Nothing else in the vendor's answer changes. The answer's
_metacarries astackjack.secretsnote that names the removed fields and the argument that brings them back. - A few fields hold ordinary values as well as secrets. Cloudflare Pages environment variables (
env_vars) and Cloudflare Workers binding values (text) keep plain and secret values in the same field, so both are left out unlessincludeSecretsis true. The tool's description says so. - To get the field, set the tool's include argument to
true. For almost every such tool it isincludeSecrets. Two keep the names they shipped with: dmarcian's user tools useincludeApiToken, andtpp_get_domain_whoisusesincludeEppPassword, which also asks TPP Wholesale for the domain's transfer code. - An answer without its secret can be a link. It can come back as the link envelope like any other result: with
resultAsLink, under your organization's Large tool results size, or when it is over the cap. The envelope then lists the removed fields insecretsRemoved. - An answer that keeps its secret is a link only when you ask for both. Set the include argument and pass
"resultAsLink": trueon the samestackjack_run_toolorstackjack_run_readonly_toolcall, and the downloaded file holds the secret. Setting both is your consent to that. With the include argument alone, the organization's Large tool results size and the oversized-result link do not store the answer: it comes back in the conversation, or astool_result_too_largewhen it is over the cap.
More than 600 tools across 40 connectors work this way today. Some examples: the MySonicWall product tools (authCode), the dmarcian user tools (api_token), the 3CX user, trunk and fax tools (the SIP passwords), the WatchGuard VPN tunnel tools (the pre-shared key), and the Xero and Employment Hero payroll tools (bank account numbers). To tell whether a tool works this way, look at the tool itself: its input schema has the include argument, and its description names the fields it removes and the argument that brings them back.
Some tools replace a whole record when you update it. If you read such a record first to send it back, read it with the include argument set to true, or the fields the read left out are missing from what you send. The descriptions of those update tools say so.
If your automation or AI client read such a field before, it now needs the tool's include argument to keep getting it.
Automation governance and replay errors
Calls made by an Automation pass additional run-specific safety gates. These codes normally mean the Automation's configuration or current run state needs attention, not that the connector is down:
See Automation guardrails and safety for the operator-facing controls behind these errors.
HTTP-layer authorization responses
Some authorization failures happen before the tool runs and return an HTTP response instead of a tool-result envelope. A missing tenant identity blocks the session. The subscription and credential responses are narrower: initialization, tool discovery, and credential-independent stackjack_* calls can still work, while a connector call (or an unrecognized request that cannot be proved safe) is refused at the HTTP layer.
One case passes this layer even though no credential loaded: a connector whose default connection is disabled, or whose default is waiting for your own sign-in, while another connection of the same connector is enabled. A call to that connector that names a usable connection with the connection argument runs; a call that names none gets the connection_default_disabled or personal_sign_in_required tool error described above, not one of the 403 responses below.
Troubleshooting recipes
"It connects, but every tool call is refused."
Ask the AI to run stackjack_session_info. If it returns pending_approval, an admin needs to approve the member on the Team page and assign tools. The connector list contains the active connectors whose credentials loaded for that request. Each connector that needs your own sign-in carries "status": "personal_sign_in_required" and says what to do; stackjack_list_connections reports the same status per connector. If an expected connector is absent or its calls are refused for some other reason, open Connectors, inspect its saved configuration, and use Re-test or stackjack_health_check; a transient load failure can also produce connector_unavailable.
"The Connectors page shows it connected, but my calls fail."
Check whether you are the workspace owner. A connector authorized by signing in stores the authorizing person's own identity, and StackJack will not run another member's calls under it. HaloPSA, NinjaOne, Reddit Ads and the Microsoft connectors (Microsoft Azure, Microsoft Graph, Microsoft Defender for Endpoint, Microsoft Exchange Online, Microsoft Purview, Microsoft SharePoint Admin, Microsoft Teams Admin and Microsoft Power Platform Admin) are examples. The tool error is personal_sign_in_required — and if that connector is the only one your organization subscribes to, the same refusal arrives as an HTTP 403 carrying "errorType": "personal_sign_in_required" instead of a tool result. The connector's card in Your personal sign-ins tells you the same thing: Authorization Required with a Connect button where you can sign in yourself, or Owner Sign-in Only where the connector has no per-member sign-in at all. Connectors configured with an API key are shared by design and work for everyone.
"A tool that worked yesterday is gone."
Plan downgrade, connector cancellation, or a narrowed client tool selection. See Why tools appear and disappear. If you just restored access, stackjack_refresh_tool_list reports the current catalog version and the refresh instructions; have the harness re-list its tools, then disconnect and reconnect if its cached list remains stale.
"The AI keeps getting not_found."
Tell it to call the connector's list/search tool first and use a returned ID. If a newly returned ID also fails repeatedly, preserve the correlation id and investigate the endpoint, permissions, and vendor product state rather than assuming another guess will help.
"Calls are failing with forbidden after I set up a least-privilege key."
The vendor key is missing a permission one of the selected tools needs. Open Connectors, open that connector's API Permissions planner, select the failing tool, and compare the Required Permissions list against the key's actual grants.
"Is StackJack itself having a problem?"
Ask the AI to run stackjack_get_service_status — it returns live platform status, component health, and any advisories targeted at your connectors.
When you contact support: include the correlationId from the error. For a support-worthy error, you can also elect to have the AI open the prefilled draft with stackjack_create_support_ticket. The draft carries the error context only; after creation, StackJack separately attempts the two best-effort diagnostic uploads described above and reports diagnosticsAttached.
Was this helpful?
More in Tools & Catalog
How MCP Tools Work in StackJackPlan Tiers and Tool GatingPermissions Page: Mapping Tools to Vendor API PermissionsChoosing Tools for Each Client and Managing Harness Tool LimitsStill need help? Ask the team