Skip to main content

Troubleshooting Bridge

Updated

This article covers the most common errors encountered when setting up connections, running syncs, and using webhooks. For each issue, the resolution steps are listed in the order most likely to fix the problem quickly.

Connection Test Fails

Symptom: Clicking Test Connection returns an error.

Steps:

  1. Open the connection and read the Last Error message. It usually names the specific problem (bad credentials, unreachable host, missing permission).
  2. Double-check all credential fields — company IDs, API keys, client secrets. Copy-paste rather than retyping to avoid character errors.
  3. For OAuth platforms (NinjaOne, Pax8, Microsoft 365, Xero), confirm the client secret has not expired or been rotated in the external system.
  4. Confirm the API user or application in the external system has not been disabled or had its permissions reduced.
  5. For on-premise systems, confirm the API endpoint is reachable from the internet (not firewalled).
  6. Fix credentials, click Test Connection again.

Sync Runs But No Records Come Over

Symptom: A sync job completes with zero records created or updated.

Steps:

  1. Check the Skipped count on the job. High skip counts usually mean records were not changed since the last sync, or a filter in the field mapping is excluding them.
  2. Confirm the entity types you expect (tickets, companies, contacts) are checked in the sync profile.
  3. Go to Field Mappings for the connection and confirm mappings exist for the entity type. If no mappings exist, apply the default template.
  4. Check the Errors tab on the job. Zero errors plus zero creates often means the external API returned no results — verify the date range on the profile is not too narrow.
  5. If company sync is involved, confirm company mappings are confirmed for the companies whose child records (contacts, tickets) you expect to see.

Credential Expiry Mid-Sync

Symptom: Syncs were working, then start failing with authentication errors.

Steps:

  1. Open the connection and click Test Connection. The error will confirm whether it is an auth issue.
  2. For OAuth platforms, the access token may have expired. Re-enter or rotate the client secret in the external system, update it in the Bridge connection, and test again.
  3. For API key platforms, check whether the API key was rotated or revoked in the external system. Generate a new key there, update the connection, and test.
  4. Once the connection test passes, trigger an immediate sync from the sync profile to catch up on missed records.

Rate Limit Errors

Symptom: Sync jobs fail partway through with "429 Too Many Requests" errors in the sync job error log.

Steps:

  1. Bridge handles HTTP 429 responses from external systems automatically using exponential backoff, so brief rate limits resolve on their own. Check if the job eventually completed.
  2. If the job failed completely, check the external system for any rate limit configuration for the API user (some PSAs cap requests per minute per integration).
  3. Switch the sync profile to a less frequent schedule (daily instead of hourly) to reduce API call volume.
  4. For large historical imports, Bridge recommends pausing and resuming if the external system is throttling requests.

Webhook Returns 401

Symptom: An external system reports your inbound webhook URL is rejecting requests with 401.

Steps:

  1. Open the inbound webhook in Bridge.
  2. Confirm the verification type matches what the external system is sending (HMAC, Basic auth, or Bearer token).
  3. Confirm the secret the external system is using matches what Bridge generated. If there is any doubt, click Regenerate Secret, copy the new secret, and update the external system.
  4. Re-send a test event from the external system and check the webhook's Logs to see whether the request arrived and what the verification result was.

API Call Returns 429 via the Gateway

Symptom: API calls through the Bridge gateway return 429 Too Many Requests.

Steps:

  1. Check the X-RateLimit-Remaining response header — it shows how many requests are left in the current window.
  2. Wait for the Retry-After window to expire before retrying.
  3. If this is a recurring problem, check the org's plan — the gateway's API call limit comes from the org's plan, not from the individual key.

Sync Job Stuck in "Running"

Symptom: A sync job has been in the running state for an unusually long time.

Steps:

  1. Open the sync job detail. If records are still incrementing, the job is still processing — large imports from busy PSAs can run for 30 minutes or more.
  2. If counts are not incrementing and the job has been running for over an hour, the worker may be stalled. Click Cancel on the job, then trigger a new sync from the profile.

FAQ

Where can I see all errors across all syncs in one place? Go to Error Recovery in Bridge. It aggregates failed records from all sync jobs, imports, flows, and webhooks. You can filter by category, retry individually, bulk retry, bulk skip, or correct the record data and save it as manually fixed. Each recurring failure pattern also carries a Suggested fix — Bridge's own guidance for that error category.

A record keeps failing on every retry — what should I do? Open the error record in Error Recovery and read the full error message and raw data. The raw data shows exactly what Bridge received from the external system. If the data itself is malformed (for example, an invalid date), fix it in the source system, then retry. If the platform rejects the data due to a validation rule, adjust the field mapping (add a transform or default value), then retry.

How do I report a problem that isn't covered here? Capture the sync job ID, the error message, and the external ID of the failing record. Include these when contacting support so the issue can be traced in the audit log.

Related