How to Troubleshoot Common Integration Issues Step by Step

Find the Broken Connection Before Making Changes

When two tools stop communicating, the visible error is not always the underlying problem. Common integration issues can interrupt customer updates, delay reports, or create duplicate records. A structured investigation helps you identify the failing step, protect your data, and choose a fix without making the situation worse.

Quick Answer

Start by identifying the affected workflow and the first failed step. Check its error message, credentials, permissions, data mapping, and service status. Test one safe change at a time. Then verify the result and recover missed records carefully.

Summary

Integration failures can happen at the trigger, connection, data, delivery, or destination stage. Use run history and error details to narrow the cause before changing settings. Restore missed work only after checking whether earlier attempts already completed.

What This Guide Covers

• How to isolate a failed integration and collect useful evidence
• What authentication, permission, data, and delivery errors mean
• How to test fixes safely and recover missed or duplicate records
• How to reduce the chance of the same problem happening again

Step 1: Define the Failure and Limit the Impact

Common integration issues become easier to investigate when you define what should happen and what happened instead. Before changing settings, identify the affected workflow and prevent further harm.

Describe the Expected and Actual Results

Write the intended workflow in one sentence. Then describe the failure in equally concrete terms.

For example:

When a new customer submits a form, a matching contact should appear in the CRM. Since Tuesday, some submissions have not created contacts.

This description is more useful than “the CRM integration is broken.” It identifies the trigger, expected result, destination, and approximate start of the issue.

Next, answer these questions:

• Does the problem affect every run or only certain records?
• Did it begin after a configuration, account, or permission change?
• Is the workflow completely stopped, delayed, or producing incorrect results?
• Is the affected data missing, duplicated, or mapped to the wrong fields?
• Are other workflows using the same connection also failing?

Use specific examples where possible. One successful run and one failed run often provide a useful starting point for comparison.

Decide Whether to Pause the Workflow

Not every error requires an immediate shutdown. A delay in a low-risk reporting workflow may be manageable while you investigate.

However, consider pausing a workflow if it is:

• Creating duplicate invoices, orders, or customer records
• Sending information to the wrong recipient
• Changing or deleting records unexpectedly
• Repeatedly triggering costly or irreversible actions
• Exposing sensitive information through an incorrect destination

Confirm the impact of pausing before you act. Some platforms queue events during a pause, while others may not. If you are unsure, ask the workflow owner or vendor support how missed events are handled.

Identify the Owner and Recovery Window

Find the person who owns the workflow and the accounts it connects. You may need different people to approve access changes, review destination records, or restart the process.

Also note the earliest affected event and the most recent confirmed successful event. These timestamps define the first version of your recovery window. You can refine it after examining the logs.

Step 2: Inspect Run History and Error Evidence

Common integration issues are visible in run history, delivery logs, or the destination application’s activity records. Find the first failed or unexpected step rather than assuming the final symptom caused the failure.

Follow One Record Through the Workflow

Choose a single affected record and trace its path:

1. Confirm the source event occurred.
2. Check whether the integration detected that event.
3. Identify any filters or conditions applied.
4. Inspect the first action that failed or produced unexpected output.
5. Check whether the destination received or changed the record.

If the trigger never fired, changing a destination field will not fix the immediate problem. Likewise, a successful trigger does not prove the final action completed.

Look for a run identifier, event identifier, timestamp, error code, and affected action. Save a short description of each finding in your incident notes.

A platform’s run status also needs context. For example, Zapier distinguishes errors from runs that stop because of an intended condition. Check your own platform’s definitions before treating every stopped run as a failure.

Interpret the Evidence

These are starting points, not guaranteed diagnoses. Providers can use different error messages and status codes.

Protect Sensitive Information in Logs

Logs can contain personal data or credentials. Share only what another person needs to diagnose the problem.

Before sending screenshots or exporting logs:

• Remove access tokens, API keys, passwords, and session identifiers.
• Avoid sharing full request bodies when a sample or field name is enough.
• Restrict access to incident notes and retain them according to your organisation’s policy.
• Use a secure support channel if detailed diagnostic data is necessary.

The OWASP logging guidance explains why useful operational logs also need appropriate security controls.

Step 3: Check Credentials, Permissions, and Access

Common integration issues begin when a connection can no longer authenticate or access the intended resource. Verify the identity and its permissions before changing the workflow itself.

Distinguish Authentication From Authorisation

Authentication asks: Who is making the request?

Authorisation asks: Is that identity allowed to perform this action?

A credential can be valid while still lacking access to a specific folder, workspace, database, or record. Conversely, a user may have the right role, but the stored token may no longer be valid.

For HTTP APIs, a 401 response generally indicates missing or invalid authentication credentials. A 403 response means the server understood the request but refused it. Always check the provider’s error details because implementation and messages can vary.

Check the Connected Account

Review these items in order:

1. Account identity: Is the integration connected to the intended user or service account?
2. Account status: Has the account been disabled, removed, or changed?
3. Credential status: Has the API key expired, been revoked, or been rotated?
4. Resource access: Can the account access the specific destination?
5. Action permissions: Can it create, update, read, or delete the relevant records?
6. Consent and scopes: Did the connection receive the permissions needed for this workflow?

For OAuth connections, access can depend on granted scopes and token status. Google’s authentication troubleshooting guidance illustrates how credential and authorisation problems can appear in an integration.

Reconnect only after identifying the right account and required permissions. Reconnecting with a different account can change what the workflow sees or where it writes data.

Apply the Smallest Safe Access Change

Avoid granting broad administrator access just to make an error disappear. Instead, request the minimum permissions needed for the affected action.

If the workflow needs to update one shared folder, for example, confirm that the connected identity can access that folder. It may not need access to every folder in the organisation.

After an access change, record who approved it and what changed. Then repeat the same safe test that previously failed.

Step 4: Verify the Trigger, Data, and Destination

Common integration issues involve data that is missing, unexpectedly formatted, or sent to the wrong place. Check each stage against the destination’s actual requirements.

Confirm the Trigger Is Receiving the Right Event

Start at the source. A workflow cannot process an event it never receives.

Check whether:

• The correct source account and workspace are selected.
• The workflow is active.
• The trigger listens for the event you expect.
• Filters include the affected record.
• The source record was created or changed after the workflow became active.
• The platform uses polling or event delivery, and whether a delay is expected.

A trigger for “new record” may not run when an existing record is edited. Likewise, a filter expecting Approved may reject approved if the platform treats those values differently.

Use a fresh test record where appropriate. Older records are not always picked up automatically after a workflow starts or reconnects.

Inspect Field Mapping and Validation

A mapping tells the workflow which source value belongs in each destination field. It can fail when a field is renamed, removed, made mandatory, or given a new format.

Pay particular attention to dates, time zones, currencies, phone numbers, and unique identifiers. A value can look reasonable to a person while failing a destination’s validation rules.

Check Webhook Delivery Where Relevant

A webhook sends an event from one system to another when something happens. If your integration uses webhooks, check the provider’s delivery history and the receiving endpoint’s response.

A delivery failure does not always mean the source event was lost forever, but recovery rules vary. For example, GitHub documents that it does not automatically redeliver failed webhook deliveries. Other providers may behave differently.

Confirm the event type, destination, response, and timestamp. If a signature check fails, involve the person responsible for the receiving service rather than disabling verification to make the event pass.

Step 5: Test a Targeted Fix and Recover Safely

Common integration issues need a controlled fix, not a collection of simultaneous changes. Form a hypothesis, change one relevant setting, and test the result against the original failure.

Test One Hypothesis at a Time

Suppose a workflow reports that an account cannot update a record. Your hypothesis might be: “The connected account can read this workspace but cannot edit records.”

A useful test would be:

1. Confirm the connected account.
2. Verify its current access to the specific workspace.
3. Request the required edit permission through the normal approval process.
4. Run one safe test using a non-sensitive record.
5. Check the destination and the run history.

If the test succeeds, document the result. If it fails, preserve the new error and investigate the next plausible cause.

Avoid testing by repeatedly creating real invoices, sending customer messages, or changing production records. Use a sandbox or test environment when available. If production testing is unavoidable, agree on a reversible test with the workflow owner.

Handle Rate Limits and Temporary Failures

A rate limit restricts how many requests a service accepts over a period. A provider may return HTTP 429 when a limit is exceeded.

If you see repeated throttling:

• Check the provider’s published limits for your account and endpoint.
• Reduce unnecessary requests or distribute work over time.
• Follow any retry instructions supplied by the provider.
• Consider whether several workflows share the same account or quota.

Stripe’s rate-limit documentation is one example of provider-specific guidance. Do not assume another service uses the same limits.

Temporary failures can justify retries, but not every error is temporary. A missing required field or revoked permission generally needs a correction first.

For transient faults, Microsoft’s retry pattern describes using appropriate delays rather than repeatedly sending requests without pause. If supported, use bounded retries, backoff, and provider guidance.

Check Whether the Action Already Happened

A timeout is especially easy to misread. The client may not have received a response, even though the destination completed the action.

Before retrying a payment, order, message, or record creation:

1. Search the destination using the original record or transaction identifier.
2. Compare timestamps and relevant values.
3. Confirm whether the action completed, partially completed, or did not occur.
4. Decide whether a retry, correction, or manual review is appropriate.

Where the provider supports idempotency, use its documented approach to reduce duplicate effects. For example, Stripe explains how idempotent requests support safe retries. Support and behaviour differ between APIs, so verify the specific operation before relying on it.

Recover Missed Events Carefully

Once the test succeeds, identify the affected records within your recovery window. Separate them into three groups:

• Not processed: The destination has no corresponding result.
• Already processed: The intended result exists, even if the original run showed an error.
• Unclear: The result needs a human check before retrying.

Start with a small batch. Confirm both the integration history and destination records before continuing.

Some providers offer replay or redelivery controls. GitHub’s webhook redelivery guidance is one example, but available history and replay behaviour are provider-specific.

Keep a record of what was replayed and what was corrected manually. This makes it easier to reconcile the final results and avoid processing the same event twice.

Step 6: Verify the Outcome and Prevent Repeat Failures

Common integration issues return when a workflow is restarted without checking the business outcome. Verify the entire path, reconcile affected records, and assign ownership for ongoing monitoring.

Confirm the End-to-End Result

A successful run status is useful, but it is not the whole answer. Check the destination directly and confirm that the right record contains the right values.

Use this verification checklist:

Test at least one normal case and one relevant edge case. For example, check a contact with all fields present and another with an optional field missing.

If you changed permissions, confirm that the connection can perform the necessary action without receiving unnecessary access. If you changed a filter, confirm that records outside the intended criteria still stop correctly.

Document the Fix for the Next Person

A short incident record can save hours later. Include:

• The workflow name and business purpose
• The first known failure and last known successful run
• The symptoms and first failed step
• The underlying cause, if confirmed
• The change made and person who approved it
• The test result and recovery method
• Any remaining records requiring review

If the cause remains uncertain, say so. “The workflow resumed after reconnecting” is not the same as proving why the connection failed.

Add Practical Monitoring

Choose monitoring based on the consequences of failure. A daily summary may be enough for a non-urgent report. A payment or customer onboarding workflow may need faster alerts and a named responder.

Review:

• Who receives an alert
• Which failures require immediate action
• Whether repeated failures create duplicate alerts
• How long failed events remain available for recovery
• How the team checks for silent failures, such as missing triggers

Finally, review critical integrations after major changes to accounts, permissions, fields, or connected applications. A small check after a change is often easier than a large recovery later.

Key Takeaways

• Define the expected result and find the first failed step before changing settings.
• Check credentials, permissions, triggers, field mappings, and destination requirements separately.
• Treat error codes as clues, then read the provider’s specific explanation.
• Test one change at a time using safe records or a suitable test environment.
• Check whether an action already completed before retrying it.
• Reconcile missed events and document the fix before closing the incident.

Conclusion

Common integration issues are easier to resolve when you follow the evidence from source event to destination. Start with one affected record, identify the first failure, and test the smallest appropriate change.

Once the workflow is working, verify the business result and recover missed records carefully. A clear owner, useful alerts, and a short incident record will make the next investigation more manageable.

Frequently Asked Questions