Why error handling matters
Errors matter because a workflow that fails for unclear reasons is hard to trust. The fastest way to recover is to separate connection problems, workflow problems, and cost or credit problems instead of treating every failure like generic downtime.
The safe public claim boundary is around the current failure labels, recent runs, reconnect handling, and approval or spend controls. It is not a promise of a full rollback or circuit-breaker control plane everywhere.
Error handling steps
1. Read the failure label first
Start with the failure reason attached to the run. The current set includes things like schema drift, approval timeout, reconnect needed, rate limited, no credits, spend cap reached, timeout, tool error, and internal error.
2. Separate reconnect issues from workflow issues
Connection-expired failures usually need reconnect work before anything else. Schema drift, tool errors, and rejected approvals usually mean the workflow or plan needs adjustment.
3. Reconnect expired apps before rerunning
When a connection expires, scheduled runs can pause and the app can raise an action-required notification. Reconnect the affected app before you expect the workflow to resume normally.
4. Fix the plan before you retry
If the run failed because the workflow was too broad, the app connection was wrong, or the write should not have happened, tighten the prompt, the plan, or the approvals before you run it again.
5. Check spend and credit limits too
Some failures are not about the workflow logic at all. If the label points to no credits or a monthly spend cap, fix the operating boundary before you retry.
6. Turn repeated failures into operating notes
If the same failure keeps appearing, add the fix to your workflow notes so the next operator knows what to check first.
Error types and handling
| Error type | What it usually means | Next action |
|---|---|---|
| Reconnect needed | A required app connection is no longer usable | Reconnect the app, then retry the workflow |
| Schema drift | The workflow no longer matches the tool or data shape it expected | Tighten or repair the workflow before rerunning |
| Approval timeout or rejection | The run could not continue through its approval checkpoint | Review the decision path and rerun only if the write still makes sense |
| Rate limited or timed out | The run hit a transient platform or provider issue | Retry carefully once the immediate issue passes |
| No credits or spend cap reached | The workflow hit a financial operating boundary | Adjust credits or cap settings before rerunning |
| Tool error or internal error | The step failed during execution | Inspect the workflow and the failed step before trying again |
Best practices
- Read the label before you react. Different failures need different fixes.
- Reconnect expired apps quickly. A broken connection can block healthy workflows from running.
- Do not blindly rerun failed workflows.Fix the underlying plan or connection problem first.
- Watch spend and credit boundaries too.Not every failure is a logic error.
- Document repeat fixes. Turn run history into practical operating notes.
Frequently asked questions
What kinds of failure labels might I see?
The current product truth includes labels such as schema drift, approval timeout, reconnect needed, rate limited, no credits, spend cap reached, timeout, tool error, and internal error.
What should I do when a connection expires?
Reconnect the affected app before expecting scheduled runs to continue. Expired connections can trigger action-required notifications and pause scheduled runs until they are fixed.
Should I retry every failure?
No. Retry only after you understand the reason. A timeout or rate-limit issue is different from schema drift, missing credits, or a connection that needs to be re-authorized.
What happens if an approval is rejected?
A rejected approval ends the waiting run without applying the proposed write. Treat that as a sign the workflow still needs tightening before you rerun it.