// troubleshooting

Connection failures

What INTEGRATION_NOT_CONNECTED and its connect_url mean, and what to do when a vendor you connected with your own credential rejects a call with a 401, 403, 429 or 5xx.

A connection is a vendor account the workspace connected with its own credential, an API key or an OAuth sign-in: a CRM, an outreach tool, a mailbox, a database, a remote MCP server. Its tools are named connection_<vendor>_* and its REST routes are /v1/connections/<vendor>/*. You pay the vendor directly, so a vendor's refusal is about your account with that vendor, never about your superagnt_ balance or plan.

Not connected yet

Over MCP, a tool whose vendor is not connected returns this tool error. It is the same shape for API-key vendors, OAuth vendors, mailboxes and remote MCP servers:

INTEGRATION_NOT_CONNECTEDjson

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Connection 'HubSpot' is not configured for this workspace.\n\nError details:\n{ ...the structuredContent below... }"
    }
  ],
  "structuredContent": {
    "error": "INTEGRATION_NOT_CONNECTED",
    "vendor": "hubspot",
    "connect_url": "https://app.superagnt.com/dashboard/<workspace-id>/connections/hubspot"
  }
}

You cannot connect an account yourself: an OAuth sign-in or a pasted credential needs a person. Hand the connect_url to the person you work for. That page offers Connect when nothing is connected, and Reconnect when a connection has stopped working. Once they tell you it is done, retry the call.

On a workspace MCP connection, agnt_connections_list shows what is connected right now.

Over REST the same situation is a 400 VALIDATION_ERROR with a message such as Connection 'HubSpot' is not configured for your workspace. Connect it in the superagnt app first., or ... has no connected account that grants it. Connect it in the superagnt app first. for an OAuth vendor.

Over MCP, an OAuth connection whose token refresh has failed for good (the vendor revoked access, or the stored grant has no refresh token) also comes back as INTEGRATION_NOT_CONNECTED, because the fix is the same: a person reconnects it. A refresh that failed for a passing reason is a PROVIDER_ERROR 502, Could not refresh <vendor> access token. Please try again shortly. Retry that one later.

The vendor rejected the call

The vendor answered	You get	What to do
401	`PROVIDER_ERROR`, HTTP 401: `Your <vendor> API key is invalid or expired. Update it in the superagnt app.`, or for OAuth, `Your <vendor> connection needs to be reauthorised. Reconnect it in the superagnt app.`	A person updates the key or reconnects, from the vendor's connection page in the superagnt app.
Access revoked (OAuth, over REST)	`PROVIDER_ERROR`, HTTP 401: `<vendor> OAuth access has been revoked. Reconnect the integration in the superagnt app.`	A person reconnects.
403	`PROVIDER_ERROR`, HTTP 403: the credential does not have sufficient permissions	A person grants the missing permission in the vendor's own settings, or reconnects with broader access.
429	`RATE_LIMITED`, HTTP 429: `Rate limited by <vendor>. Please try again later.`	Back off and retry. This is the vendor's limit on your account.
Another 4xx	`PROVIDER_ERROR` with the vendor's status	Read the vendor's error and fix the call.
5xx, or no answer	`PROVIDER_ERROR`, HTTP 502	Retry with backoff. If it keeps failing, check the vendor's status page.

Over MCP, a vendor rejection also carries the vendor's own answer in structuredContent: providerId, providerName, upstreamStatus (what the vendor returned) and upstreamError (the vendor's error body, with credential-like fields removed and long values cut). Read upstreamError first: it usually names the field or permission the vendor objected to.

Other connection errors

Code	Status	What it means	What to do
`PROVIDER_NOT_FOUND`	404	There is no connection vendor with that name, or it is not available through the connections proxy.	Check the vendor name. `agnt_tools_search` lists the connection families this server can serve.
`PROVIDER_UNAVAILABLE`	503	The vendor is not set up correctly on our side.	Not yours to fix. Open a ticket with the vendor name and the time.

When to open a ticket

Most connection failures are fixed by the person you work for, in the superagnt app or in the vendor's own settings, so start there. Open a ticket with agnt_support_ticket_create and category connection when a connection shows as connected but every call still fails the same way, when the Connect or Reconnect flow itself fails, or when you get PROVIDER_UNAVAILABLE. Include the vendor, the tool name or path, the upstreamStatus and the time. Never include the credential. See Getting help.