read thedocs.

[ docs // guides & reference ]

Connector setup guides, tool references, auth flows, and platform concepts — everything you need to run StackJack, in one place.

Browse the Docs All Connectors

34 connectors documented // 6,712 tools referenced // setup, auth & platform guides

↓

No pages match that search. Clear it

← All documentation

Tool Errors and Troubleshooting

When a tool call fails, StackJack never returns a bare stack trace or a silent failure. The AI receives a structured JSON error envelope designed so it can understand what went wrong, relay it to you in plain language, and offer sensible next steps. This page documents that envelope, every error type, and how to troubleshoot the common ones.

The error envelope

A failed tool call returns JSON shaped like this (fields that don't 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 by StackJack itself (plan, billing, allowance) carry the same envelope without the upstream fields — for example a monthly_limit_exceeded error's message includes your usage, your limit, and the billing-cycle window (start–end), but no httpStatus or upstreamError.

Field by field:

Field	Meaning
`errorType`	A stable machine-readable code (full list below).
`retryable`	Whether simply trying again may succeed (true for rate limits and transient upstream failures).
`message` / `guidance`	Plain-language explanation and suggested action, written for the AI to relay to you.
`httpStatus`	The HTTP status the vendor API returned, when the failure came from upstream.
`upstreamError`	The vendor's own error body, passed through so nothing actionable is lost — with credential-shaped content redacted, and truncated to 2,000 characters.
`correlationId`	A trace id for this exact request. Quote it to StackJack support — it lets them find the same request in their telemetry immediately.
`supportTicketDraft` / `nextActions`	A prefilled support-ticket draft and a pointer to `stackjack_create_support_ticket`. The AI is explicitly told to ask for your authorization before opening a ticket.

Failed calls never count against your monthly allowance — only successful calls consume quota.

Error types: access and billing gates

These are raised by StackJack before the vendor API is ever contacted:

errorType	Meaning	What to do
`tool_not_allowed`	The tool isn't in this MCP client's (or team member's) tool selection.	An admin updates the client's tool selection on Endpoints (or the member's grants on Team).
`plan_upgrade_required`	The tool needs a higher plan tier than the connector subscription has.	Upgrade that connector's plan, or use a lower-tier alternative tool.
`subscription_past_due`	The connector subscription's renewal payment failed.	Update the payment method on the billing page.
`subscription_paused`	The connector subscription is paused.	Resume it on the billing page.
`subscription_canceled`	The connector subscription was canceled.	Resubscribe to restore access.
`subscription_inactive`	The connector subscription is in some other non-active billing state.	Check the subscription on the billing page.
`subscription_period_ended`	The billing period ended and no renewal has been recorded yet.	Usually resolves when the renewal processes; check the billing page if it persists.
`monthly_limit_exceeded`	The connector's call allowance for the current billing cycle is used up. The message shows usage, limit, and the billing-cycle window.	Wait for the cycle reset or upgrade the plan.
`instance_version_unsupported`	The tool requires a newer version of your connected product instance than it reports. (Rare — no tools currently enforce a real version floor.)	Upgrade the connected instance or use an equivalent tool.

Error types: upstream vendor API failures

When your connected product's API rejects or fails a call, StackJack classifies the HTTP status:

errorType	HTTP status	What it usually means
`bad_request`	400	The vendor rejected the request parameters. The guidance includes a snippet of the vendor's response so the AI can self-correct.
`authentication_error`	401	The connector credentials were rejected. Re-validate or reconfigure them on the Connectors page.
`forbidden`	403	Credentials are valid but lack permission for this operation in the vendor product. Grant the missing permission on the vendor side (the Permissions page shows what each tool needs).
`not_found`	404	Almost always the AI used a wrong or stale ID — not an outage. The guidance tells the AI to verify the ID with a list/search tool first. Expected during normal AI exploration; not a platform fault.
`rate_limited`	429	The vendor's own rate limit tripped. Retryable — the AI should wait a moment and try again. StackJack already self-throttles below most vendors' limits, so sustained 429s are unusual.
`upstream_server_error`	500	The vendor API had an internal error. Usually transient — retry.
`service_unavailable`	503	The vendor API is down or in maintenance. Retry later.
`gateway_timeout`	504	The vendor API timed out. Retry later.
`connector_api_error`	other	Any other vendor API failure; see `upstreamError` for the vendor's detail.

A note on 404 and 429 semantics: these two are treated as expected environmental outcomes, not incidents — a wrong ID or a busy vendor API is part of normal operation. The other 4xx codes (401/403) point at credential or permission configuration and are worth acting on.

Error types: credentials and configuration

errorType	Meaning	What to do
`connector_not_configured`	The tenant has a subscription but no working credentials for this connector.	Add or fix credentials on the Connectors page.
`authorization_expired`	A stored authorization (for example an OAuth refresh chain) is definitively no longer valid.	Reconnect/re-authorize the connector in the portal.
`refresh_in_progress`	Another request is refreshing this connector's token right now.	Retry in a few seconds.
`refresh_token_persistence_failed`	A rotated token could not be saved — StackJack fails safe rather than risk breaking the credential chain.	Retry; contact support with the `correlationId` if it recurs.
`capability_not_enabled`	The vendor API key lacks an optional capability. Today this is IT Glue's Password Access: password tools return this until you regenerate the IT Glue key with password access enabled.	Follow the guidance in the error — it names the exact capability to enable.

Error types: everything else

errorType	Meaning
`timeout`	The call exceeded StackJack's time budget waiting on the vendor. Retryable.
`network_error`	StackJack couldn't reach the vendor API (DNS/connectivity). Retryable.
`connector_concurrency_limit`	StackJack briefly caps how many of your calls can hit the same vendor object endpoint at once (mirroring the vendor's own concurrent-request cap), and no slot opened up within the short wait window — so the call was never sent to the vendor. This is StackJack's own limiter, not a vendor rate limit (429). Retryable: retry in a moment, and avoid firing many calls at the same entity type in parallel (for example several get-all or aggregation tools at once). Currently only the Autotask connector applies this limiter (up to 3 concurrent calls per object endpoint, with a wait of about 10 seconds).
`validation_error`	An input problem: a tool parameter failed validation (the message names the parameter and valid values), a JSON parameter was malformed, or — less commonly — the vendor API returned a JSON shape the tool didn't expect.
`internal_error`	An unexpected StackJack-side failure. Contact support with the `correlationId` if it persists.
`feature_disabled`	Returned by automation platform tools (`stackjack_run_agent`, `stackjack_list_agents`, `stackjack_get_run_transcript`) when Agentic Orchestration isn't enabled for your tenant. Contact StackJack support to enable it.
`capacity_exceeded`	The automation runner is at capacity — all execution slots are busy (or a transcript fetch was rate-limited). Retryable — try again shortly.

Connection-level errors (before any tool runs)

If the harness can't even establish an authorized session, the failure happens at the HTTP layer rather than as a tool error:

Response	Meaning	What to do
`401 {"error":"Tenant not resolved"}`	The MCP client credentials are wrong, rotated, or revoked.	Check the client's credentials on Endpoints; re-copy them into the harness.
`403 {"error":"No active connector subscriptions found"}`	The tenant has no active connector subscription.	Subscribe to at least one connector. StackJack platform tools (`stackjack_*`) still work in this state.
`403 {"error":"No connector credentials configured for your active subscriptions"}`	Subscriptions exist but no connector has working credentials.	Configure credentials on the Connectors page. Platform tools still work.

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. Otherwise check the connectors list in the response — a connector showing hasCredentials: false explains failures for that connector's tools.

"A tool that worked yesterday is gone." Plan downgrade, connector cancellation, or a narrowed client tool selection. See Why tools appear and disappear. Ask the AI to run stackjack_refresh_tool_list if you've just restored access.

"The AI keeps getting not_found." The AI is probably guessing IDs. Tell it to call the connector's list/search tool first and use a returned ID — that is exactly what the error guidance instructs it to do.

"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 the Permissions page, 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, or simply authorize the AI to open the prefilled support ticket via stackjack_create_support_ticket — the draft carries the error context and diagnostics automatically.