Loading tutorials…
Loading tutorials…
Your Zap was working last week. Today, Zap History shows red. This walks through the diagnostic flow specialists run — OAuth, payload shape, rate limits, schema drift — in the order that surfaces the issue fastest.
Who this is forOperators staring at a halted or repeatedly-erroring Zap in Zap History. If you have already tried "turn it off and on again" and it did not help, the issue is one of 5-7 specific failure modes — diagnose in order.
What you'll need
Step 1
Zapier → Zap History (left nav) → filter by Zap name or status = Error. Click the most recent failed run. Read the error message word-for-word.
Open Zapier → left nav → Zap History.
Filter: Status = Errored (or Halted) and Zap = [your broken Zap]. Sort by most recent.
Click the most recent failed run. Expand each step.
Find the step with red status. Click it. The error message displays at the top of the step detail.
Copy the error message text verbatim — you will Google it if needed, and exact wording matters.
Also capture: the input data to the failing step, the timestamp, and how many runs have failed (a count of similar failures helps diagnose schema changes vs. transient blips).
Step 2
Group the error into one of: OAuth/auth, rate limit, missing field, invalid value, destination 5xx, unknown. Each has a specific fix path.
OAuth/auth errors ("Authentication failed", "401 Unauthorized", "Invalid token"): the connection between Zapier and one of your apps expired or was revoked. Fix in step 3.
Rate limit errors ("429 Too Many Requests", "Rate limit exceeded"): you are hitting the destination app's API rate cap. Fix in step 4.
Missing field errors ("Required field X is missing", "Field cannot be empty"): the trigger or upstream step did not return a value the action requires. Fix in step 5.
Invalid value errors ("Invalid email", "Date format incorrect"): the value passed is wrong type/shape. Often a sign the upstream app changed its data format.
Destination 5xx ("500 Internal Server Error"): the destination app is having issues. Usually transient. Auto-replay handles these on Pro+.
"Unknown error" or vague messages: usually a payload shape change. Compare current trigger sample to the original. Fix in step 6.
Step 3
Open Zapier → App Connections → find the affected app → re-authenticate. Then in the Zap editor, re-select the connection (sometimes required).
Zapier → My Apps (or App Connections) in the left nav.
Search for the affected app. Click it.
Click "Reconnect." Complete the OAuth pop-up flow fully. Do not close the window mid-flow.
If the reconnect fails, often the underlying account changed (password reset, 2FA added, scope revoked). Resolve in the source/destination app first, then retry.
After reconnect, open the broken Zap → editor → click the step using the affected app → in the "Account" dropdown, re-select the reconnected account (sometimes Zapier holds the old reference).
Click "Test step." If it passes, replay errored runs from Zap History.
Step 4
Add a Delay step before the rate-limited action. Reduce per-day Zap volume via filters. Or batch operations using the destination app's bulk endpoint.
Open the destination app's API docs. Find the rate limit (e.g., HubSpot: 100 req/10s, Slack: 1 msg/s per channel).
Calculate: how many Zap runs/minute hit this action? If above the limit, you need throttling.
Option A: add a "Delay by Zapier" step before the action. Set a delay that brings throughput under the cap (e.g., 1 second per run for Slack).
Option B: add a Filter step earlier in the Zap to reduce volume (skip runs that do not need the action).
Option C: replace the per-record action with a bulk-API call via Code by Zapier (collect 50 records, send one API call). Most effective for high-volume Zaps.
After fixing, replay the errored runs from Zap History.
Step 5
The trigger or upstream step is no longer returning a field your action needs. Identify which step changed, update the mapping or add a fallback.
In the failed run detail, expand the failing step. Find the field marked "missing."
Trace back: which earlier step was supposed to return that field? Click that step. Inspect its output.
If the field is missing from the output: the source app changed its schema (silent migration), or the source record is now incomplete (a real null), or the OAuth lost scope to that field.
For schema change: update the field mapping to use the new field name. Test. Save.
For real nulls: add a Filter by Zapier before the failing step that skips runs without the field. Better than halting the whole Zap.
For scope loss: re-auth as in step 3, granting the missing scope (you'll see this if reconnecting prompts for new permissions).
Step 6
If "unknown error" or fields are unexpectedly empty, the source app likely changed its API. Re-test the trigger to get a fresh sample. Compare to the original.
Open the Zap editor. Click the trigger step.
Click "Test trigger" to pull a fresh sample.
Compare the fresh sample to the original sample (which is what your action mappings were configured against).
Common changes: field renamed (e.g., "user_email" → "email"), field nested (e.g., flat "email" → nested under "user.email"), field type changed (string → object).
For each changed field, update the action mapping to point to the new path. If the change is severe, you may need to add a Code by Zapier step to reshape the payload before downstream actions consume it.
After updating, replay errored runs that fit the new shape (older runs from before the change may still need manual handling).
Step 7
After fixing, replay the errored runs from Zap History. Monitor for 24-48 hours to confirm the issue is resolved.
In Zap History, filter to errored runs since the issue started.
For each, click "Replay." (Newer Zapier versions support bulk replay.)
Watch the replays succeed in real-time. Confirm destination records appear correctly.
For the next 24-48 hours, check Zap History daily. Confirm no new errors of the same type.
If errors recur, the fix did not address the root cause — return to step 2 and re-diagnose.
Once stable, document the issue and fix in your runbook so the next on-call person can resolve in 5 minutes instead of 60.
Common mistakes
Skipping the error message text
What goes wrong: You diagnose based on intuition rather than the actual error. Wastes 30-60 minutes chasing the wrong fix. Discover at the end the error message said exactly what was wrong.
How to avoid: Always start by reading the error message verbatim. Copy it. Search it. The first 5 minutes of debugging is reading, not clicking.
Not checking when the issue started
What goes wrong: You think the issue is fresh but it started 3 weeks ago. By the time you fix, 3 weeks of data is lost and the replay window may have expired.
How to avoid: In Zap History, filter by status = error and sort by oldest first. Find the first errored run after the last successful run. That timestamp tells you the change date — correlate with any platform updates or schema migrations.
Replaying before fixing
What goes wrong: You replay an errored run before fixing the underlying issue. It fails again. You assume the replay system is broken. Confusion compounds.
How to avoid: Always fix first, then replay. Run a single test replay on one record to confirm the fix works, then bulk replay the rest.
Fixing one Zap, ignoring related Zaps
What goes wrong: Your HubSpot OAuth expired. You reconnect for one Zap. The other 8 HubSpot Zaps still have the old reference and continue failing. You think you fixed it.
How to avoid: When you reconnect an app, audit every Zap that uses that app. Update all references. Replay all errored runs.
No runbook entry after fix
What goes wrong: You spend 90 minutes diagnosing today. In 3 months, the same issue recurs. You spend 90 minutes diagnosing again because nothing was written down.
How to avoid: After every non-trivial fix, write 3-5 lines in a runbook: what broke, how you diagnosed, how you fixed. Next time, the fix takes 5 minutes.
Believing "it works now" without monitoring
What goes wrong: You fix the Zap, see one run succeed, declare victory. The issue recurs intermittently for 2 more weeks before you notice.
How to avoid: After every fix, monitor for 48 hours. Check Zap History each day. Confirm zero new errors. Only then close the ticket.
Recap
Done — what's next
How to set up error handling in Zapier (auto-replay, monitoring, fallback paths)
Read the next tutorial
Hand it off
Debugging one Zap is a 60-90 minute project. Debugging the same kind of issue across 20 Zaps every quarter is a job. EverestX automation specialists own ongoing Zap maintenance — fix once, monitor always, document everything — typically $300-700/mo at $14-16/hr.
See specialist rates
Zapier → Zap History → filter Status = Errored or Halted. Sort by most recent. This shows every failing Zap across your account in one view.
Errored = a single failed run. Halted = Zapier has stopped retrying because errors repeated. A halted Zap is effectively off until you investigate. Errored runs may auto-recover (with auto-replay); halted Zaps require manual fix + replay.
Yes — open the Zap → click "..." menu → Version History (available on Pro+). Restore any prior version. This is helpful when a recent edit broke production.
Three usual causes: (1) the action targeted the wrong account (e.g., a test HubSpot instead of production), (2) the destination app filtered/deduplicated based on a field, (3) the action ran successfully but to a record you cannot see in your view. Check Zap History — the step output usually contains the destination's record ID.
30 days on Pro+, 7 days on Starter, 24 hours on Free. Past that window, failed runs are deleted from history and cannot be replayed inside Zapier. Recover from the source app's records or accept the data loss.
Zapier
Default Zapier behavior on errors: fire once, fail silent, halt the Zap. Lose data. This walks through auto-replay, dedicated error Zaps, fallback paths, and the monitoring discipline that catches breaks within an hour — not after the next quarterly review.
Zapier
One trigger, three or four actions. Easy to draw on a whiteboard, easy to break in production. This walks through chaining, naming, and the error scenarios that hit you on day 30, not day 1.
Zapier
If your app sends data and Zapier needs to receive it instantly, polling won't cut it. Webhooks by Zapier handle the instant case — once you get past the auth, payload-shape, and parsing gotchas that bite every first-timer.
Zapier
DIY Zapier is great until your Zap count climbs past 10 and you stop knowing what is running. This is the honest framework: when the cost of self-managing automations exceeds the cost of a specialist, and how to tell which side you are on.
HubSpot Marketing Hub
Workflows are the engine under HubSpot's marketing automation. They are also where 80% of the silent breakage happens — wrong enrollment criteria, missing re-enrollment toggles, branch logic that loops. Here's how specialists build them so they hold up.