Troubleshooting Connection Issues

Common connection problems and how to resolve them.

Overview

When a workflow step calls an upstream service, the call goes through the workspace connection that the step references. If that connection's credential is invalid, expired, missing a scope, or being rate limited by the upstream service, the step fails and surfaces the underlying error in the execution log.

Most connection failures fall into a small number of patterns. This guide covers the ones you are most likely to hit and the fastest fix for each. For repeated or unusual failures, the execution log shows the exact upstream response, which is the best starting point.

OAuth Token Expired or Revoked

The connection status moves to Reauthorize and steps fail with an authentication error. Spojit refreshes OAuth tokens automatically, so this usually means the refresh token itself was revoked (consent removed on the upstream service, account deleted, password reset on some providers).

Open the connection from Connections and click Reconnect.
Sign in on the upstream service and re-grant the requested scopes.
Re-run any failed executions from the execution log.

Invalid API Key

The step fails with 401 Unauthorized or the upstream's equivalent. The key may have been rotated, deleted, or copied with stray whitespace.

Generate a fresh key on the upstream service.
Open the connection, paste the new key, and save. Spojit re-verifies the credential.
Where the service offers scoped keys, confirm the new key has the same or broader scopes than the old one.

Connection Timeout

The upstream service did not respond within the connector's timeout. This is almost always a transient upstream issue.

Check the upstream service's status page.
Retry the workflow from the execution log once the upstream service is healthy.
For self-hosted services, confirm the service URL on the connection is reachable from Spojit's egress.

Permission Denied

Authentication succeeds but the upstream service rejects the specific call with 403 or an equivalent. The credential is valid but does not have the scope or role needed for that tool.

For OAuth: click Reconnect to grant the additional scope on the consent screen.
For API key: regenerate the key with the required scope on the upstream service and update the connection.
Check the upstream service's role assignments if the credential is tied to a specific user account.

Rate Limited

The upstream returns 429 Too Many Requests. The workflow is calling the service faster than the upstream allows.

Slow down a Loop node by lowering its concurrency or batching items.
Reduce the frequency of a Schedule trigger that is fanning out into many upstream calls.
For unavoidable bursts, configure retry with backoff on the connector node so transient 429s recover automatically. See Understanding Retry and Error Handling.

Tips

Start from the execution log. The upstream's raw error message is more diagnostic than the connection's status alone.
Run the failed step in isolation after a fix by re-running from the execution log; you do not need to wait for the next scheduled trigger.
When in doubt about a credential, regenerating it on the upstream service is usually faster than debugging which character was wrong.

Common Pitfalls

Editing the wrong environment's connection - Make sure the connection you are fixing matches the workflow that failed; a sandbox and production connection can have the same connector and similar names.
Reconnecting as a different upstream user - The OAuth consent screen may default to whichever account is signed in. Reauthorizing as a different person changes who the connection acts as.
Treating rate limits as bugs - Repeated 429s point at workflow shape (too many parallel calls), not a broken connection. Look at the calling node before you touch the credential.
Stale local cache - After updating a connection, refresh the workflow designer tab to make sure you see the latest connection state.

Learn More

Connections documentation