Troubleshooting a connector
What the common failures look like, and what each one actually means.
On this page
Start at Settings → Integrations and open the connector. The status line and the last ten calls are on that screen.
Authentication expired
Looks like: every call failing since a particular timestamp, with the same error.
Means: a token or password changed in the other system, or an OAuth grant expired.
Fix: reauthenticate. If it recurs monthly, the account being used has a password rotation policy — move to a service account or an OAuth app that does not expire on a schedule.
Permission denied on some records
Looks like: most calls succeeding, a consistent subset failing.
Means: the account has access to some records and not others. Usually a permission model in the other system that nobody mapped when the connector was set up.
Fix: widen access in the other system, or narrow which cases the connector runs for. Do not widen the connector's scope in Hendl — that is not where the restriction is.
Field not found
Looks like: calls failing with a named field, starting abruptly.
Means: somebody renamed or removed a field in the other system.
Fix: update the field mapping. This is the most common failure by a distance, and it is worth asking the other system's owner to tell you before they rename things rather than after.
Slow, not failing
Looks like: calls succeeding but taking seconds, and workflow steps lagging.
Means: the other system is rate limiting, or under load.
Fix: reduce the frequency of the signal driving the calls. A connector polling every minute for something that changes twice a day is a self-inflicted rate limit.
When to contact support
If the last ten calls show a failure you cannot place, send us the connector name and the timestamp of a failing call from Contact support. Those two facts are enough for us to find it.