Sync Errors
If you've connected an integration (QuickBooks, Google Calendar, Zapier, etc.) and something isn't syncing, here's how to diagnose.
QuickBooks Online sync issues
Check the sync status
Settings → Integrations → QuickBooks → Sync Status shows:
- Last successful sync time
- Any pending items
- Any errored items
Common QB sync errors
"Customer name mismatch"
HandyBook found a customer that doesn't have an exact match in QB. Resolve:
- Manual match (link the HB customer to the QB customer)
- Create new in QB (HB pushes a new record)
- Skip (don't sync this customer)
"Account mapping incomplete"
HandyBook tried to sync an expense to a category you haven't mapped to a QB account. Fix in Settings → Integrations → QuickBooks → Account Mapping.
"QuickBooks rate limit"
QB API has rate limits. If you've made many changes at once, sync slows. Auto-retries.
"QuickBooks token expired"
Reauthorize by clicking Reconnect in Integration settings.
Force a full re-sync
Settings → Integrations → QuickBooks → Force Re-sync runs a fresh sync from scratch. Use sparingly — it's slow and can flag many already-matched items as conflicts.
Google Calendar sync issues
Events not appearing in Google
- Confirm sync is on
- Check the right Google Calendar is selected (not your secondary or shared one)
- Wait a minute — sync isn't instant
Events appear in Google but disappear minutes later
- Possibly a conflict with another sync (e.g. both HB and Outlook are pushing to the same Google Calendar). Pick one source of truth.
- Or you have a CalDAV plugin overwriting — disconnect.
Google events not appearing in HB
- Two-way sync must be enabled (default is one-way)
- Settings → Calendar Sync → toggle "Block HB calendar with external events"
Reauthorize
If Google asks to reauthorize: Settings → Integrations → Google Calendar → Reconnect.
Zapier sync issues
Zap not running
- Check Zapier dashboard for the Zap status
- Failed Zap runs show in Zapier with the reason
- Common: rate limit hit, invalid data field
Action firing wrong number of times
- Filter the Zap better — Zapier may be picking up too many events
- Use Zap conditions to narrow trigger
Stripe sync issues
Payments not appearing in HandyBook
- Ensure Stripe is connected to HandyBook (not a separate Stripe account)
- Check Stripe Dashboard for the payment — is it showing there?
- HB pulls payment events via webhook; if your webhook is broken, contact support
Refund not reflecting in HB
- Allow 5-10 minutes for Stripe → HB sync
- Force re-sync via Settings → Payments → Sync from Stripe
API / Webhook issues
Webhooks failing
- Settings → Developer → Webhooks → endpoint → Logs
- See HTTP response from your endpoint
- 5xx errors mean your server is down or buggy
- 4xx errors mean your endpoint is rejecting
API rate limit hit
- HB returns 429 status
- Back off and retry with exponential backoff
- Higher limits available on Business tier
General sync best practices
- Don't edit the same record in both systems simultaneously — leads to conflicts
- Pick a system of record for each data type (e.g. invoices in HB, payroll in Gusto, etc.) and let sync flow one direction primarily
- Reconcile monthly — even with auto-sync, do a manual check end-of-month
Logs and diagnostics
For any integration:
- Settings → Integrations → [name] → Logs
- Last 30 days of sync events with timestamps and outcomes
- Useful for support tickets if you need help
When to escalate
If you've tried:
- Reconnecting the integration
- Force re-sync
- Checking logs
- Reading this article
…and still failing, contact support@handybook.app with:
- Integration name
- Specific error message
- Last successful sync time
- Screenshot of the issue
FAQ
My QuickBooks invoices show different totals than HandyBook — why? Common: an invoice was edited in HB after sync. Force re-sync that specific invoice. Or QB is calculating tax differently — check both tax setups match.
Can I temporarily pause an integration? Yes — Settings → Integrations → [name] → Pause. Resumes when un-paused.
Will pausing lose data? Events that occur during pause are logged. When you resume, queued events sync. If pause is very long (weeks), some events may be skipped — re-sync from a date.
How long do sync logs stay? 30 days standard; 90 days on Business tier.
Can I get notified when a sync fails? Yes — Settings → Integrations → [name] → Notify on failure. Email/push alerts on sync errors.