Troubleshoot connection errors

Use this guide when a connection fails during OAuth, a connected account shows an unexpected status, or a tool call fails. Start with the diagnostics below, then open the matching scenario.

For connection setup errors (redirect URI mismatch, session expiry, token exchange failures), also see Common scenarios on Configure connections.

Start with diagnostics

Check the connected account status first. That tells you whether the user never finished OAuth, still needs identity verification, tokens expired, or the account is disconnected.

Python

account = scalekit_client.actions.get_connected_account(
    identifier="user_123",
    connection_name="gmail",
)

print(account.status)  # ACTIVE, EXPIRED, PENDING_AUTH, PENDING_VERIFICATION, or DISCONNECTED
print(account.scopes)

Node.js

const account = await scalekit.actions.getConnectedAccount({
  identifier: 'user_123',
  connectionName: 'gmail',
});

console.log(account.status); // ACTIVE, EXPIRED, PENDING_AUTH, PENDING_VERIFICATION, or DISCONNECTED
console.log(account.scopes);

Status	Meaning
ACTIVE	Credentials are valid; tool calls should work
EXPIRED	Access token expired and needs refresh or re-authentication
PENDING_AUTH	User has not finished OAuth, or re-authentication is in progress
PENDING_VERIFICATION	OAuth succeeded; user identity verification is still required
DISCONNECTED	Account was manually disconnected

If status is ACTIVE but a tool still fails, run a read-only tool (for example gmail_get_profile) to confirm the connection end to end. The error message usually points to scopes, credentials, or provider rate limits.

Connected account status

Status is PENDING_AUTH

The user has not finished OAuth, or you initiated re-authentication and the user has not completed it yet. Generate an authorization link and send it through your app (email, in-app prompt, or settings page).

Python

if account.status == "PENDING_AUTH":
    link = scalekit_client.actions.get_authorization_link(
        connection_name="gmail",
        identifier="user_123",
    )
    print(link.link)

Node.js

if (account.status === 'PENDING_AUTH') {
  const link = await scalekit.actions.getAuthorizationLink({
    connectionName: 'gmail',
    identifier: 'user_123',
  });
  console.log(link.link);
}

Status changes to ACTIVE after the user completes OAuth (or to PENDING_VERIFICATION if your connection requires identity verification).

Status is PENDING_VERIFICATION

OAuth succeeded, but Scalekit is waiting for the user to complete identity verification before the account becomes ACTIVE. Send the user through your verification flow.

See Verify user identity for configuration and API calls. After verification succeeds, status should move to ACTIVE.

Status is EXPIRED

The access token expired and Scalekit could not refresh it automatically. Try a manual refresh first. If refresh fails, send the user a new authorization link.

Python

try:
    account = scalekit_client.actions.refresh_connected_account(
        identifier="user_123",
        connection_name="gmail",
    )
    if account.status != "ACTIVE":
        link = scalekit_client.actions.get_authorization_link(
            connection_name="gmail",
            identifier="user_123",
        )
        print(link.link)
except Exception as exc:
    print(exc)

Node.js

try {
  const refreshed = await scalekit.actions.refreshConnectedAccount({
    identifier: 'user_123',
    connectionName: 'gmail',
  });
  if (refreshed.status !== 'ACTIVE') {
    const link = await scalekit.actions.getAuthorizationLink({
      connectionName: 'gmail',
      identifier: 'user_123',
    });
    console.log(link.link);
  }
} catch (error) {
  console.error(error);
}

Status is DISCONNECTED

The connected account was manually disconnected in Scalekit or the user removed your application’s access at the provider (for example Google Account > Third-party access). Re-authentication is the only fix.

Send a new authorization link and explain that the user disconnected the integration. Pending tool executions fail until the user reconnects.

Handle disconnected accounts in your app

Surface DISCONNECTED status in your UI and stop scheduling tool calls for that connected account until the user reconnects.

OAuth flow errors

The provider returns an error on the callback URL

Read the error and error_description query parameters on the callback. Common values:

Error	Meaning	What to do
access_denied	User cancelled consent	Offer to restart the flow
invalid_request	Malformed authorization request	Check scopes and connection configuration
unauthorized_client	OAuth client not authorized	Verify credentials in AgentKit > Connections
invalid_scope	Scope not valid for this app	Update scopes on the connection and retry
server_error	Provider-side failure	Retry after a few minutes; check provider status

Log both parameters in development. Do not expose raw error_description text to end users.

failed_to_exchange_token after consent

Token exchange failed after the user approved access. See Common scenarios on Configure connections for retry steps, status page checks, and what to send support.

Redirect URI mismatch

The redirect URI in the provider’s OAuth app must match the URI shown in Scalekit exactly — protocol, host, path, and trailing slashes included.

1. Open AgentKit > Connections and select the connection
2. Copy the Redirect URI from Scalekit
3. Paste it into the provider’s OAuth app settings (Google Cloud Console, Azure portal, and similar)
4. Save both sides and restart the connection flow

Match the string exactly

Watch for http vs https, missing or extra trailing slashes, and port numbers in local development.

Session expired or invalid on the callback page

The OAuth verification session timed out before the provider redirected back. Close the window and start the connection flow again. No configuration change is required.

See also Common scenarios on Configure connections.

Invalid state parameter

Scalekit validates the state parameter for CSRF protection. If you see this error:

1. Confirm cookies are enabled in the browser
2. Finish the flow in the same browser you started it in
3. Clear stale cookies and restart the flow
4. Check for large clock skew between client and server

Tool execution failures

Tool fails with an auth error but status is ACTIVE

Work through these checks in order:

1. Confirm status with get_connected_account
2. Call refresh_connected_account / refreshConnectedAccount
3. Compare account.scopes to the scopes your tool requires
4. Run a read-only tool (for example gmail_get_profile) to isolate the failure

Python

account = scalekit_client.actions.get_connected_account(
    identifier="user_123",
    connection_name="gmail",
)

scalekit_client.actions.refresh_connected_account(
    identifier="user_123",
    connection_name="gmail",
)

result = scalekit_client.actions.execute_tool(
    identifier="user_123",
    tool_name="gmail_get_profile",
    tool_input={},
)
print(result.data)

Node.js

const account = await scalekit.actions.getConnectedAccount({
  identifier: 'user_123',
  connectionName: 'gmail',
});

await scalekit.actions.refreshConnectedAccount({
  identifier: 'user_123',
  connectionName: 'gmail',
});

const result = await scalekit.actions.executeTool({
  identifier: 'user_123',
  toolName: 'gmail_get_profile',
  toolInput: {},
});
console.log(result.data);

Insufficient permissions or forbidden errors

The user granted fewer scopes than your tool needs. Check granted scopes on the connected account, then send a new authorization link after you update scopes on the connection.

See Configure scopes on the connections page. After you add scopes to a connection, existing users must re-authenticate.

Provider-specific errors

Google: “Access blocked” or “This app isn’t verified”

Google blocks unverified apps that request sensitive scopes, or the Workspace admin blocked third-party apps.

• During development, use test users or click Advanced > Go to app (unsafe) on the consent screen
• For production, complete Google app verification or use less restrictive scopes
• Workspace admins may need to allowlist your OAuth client

Microsoft 365: AADSTS65001 consent errors

The tenant has not granted consent for the permissions your connection requests.

1. Open the app registration in Azure portal
2. Confirm API permissions match your connection scopes
3. Grant admin consent if the tenant requires it
4. Retry the connection flow

Microsoft 365: AADSTS50020 user not found

The signed-in account is not in the expected Microsoft 365 tenant, or the tenant blocks external applications. Confirm the user has a valid work or school account and that tenant policy allows your app.

Slack: OAuth access denied or workspace restrictions

The user may lack permission to install apps, or the workspace admin must approve the app first. Ask a workspace admin to approve the installation, or test with a workspace where you control app policy.

Configuration and rate limits

Invalid client or client authentication failed

OAuth credentials on the connection do not match the provider’s console.

1. Open AgentKit > Connections and select the connection
2. Compare Client ID and Client Secret to the provider’s OAuth app
3. Regenerate the secret in the provider console if it may have rotated
4. Create a new connected account and retry OAuth

Authorization succeeds but tools fail on scope

The connection is missing scopes your tools require. Update scopes in the connection form, then have users re-authenticate. Scopes on existing tokens do not expand automatically.

Rate limit or quota exceeded

The provider rejected requests because you exceeded its quota. Back off and retry with exponential delay, reduce call frequency, and cache read results where possible.

Bring Your Own Credentials (BYOC) gives you a dedicated quota on providers that support separate OAuth apps. See your connector’s setup guide for BYOC steps.

Get help

Open AgentKit > Connected Accounts in the dashboard and review status, refresh history, and tool execution logs for the affected account.

When you contact support, include:

• Connected account ID or user identifier
• Connection name (for example gmail, slack)
• Full error text and timestamp
• Steps that reproduce the failure

Related guides:

• Configure connections — setup, scopes, and common OAuth errors
• Manage connected accounts — per-user connection state and credentials