How to Fix Common Sync Errors in SalesToBooks
Troubleshooting guide for the most common sync issues: expired tokens, unmapped categories, API errors, and how to resolve them.
Founder & CEO
Sync Errors Are Usually Quick Fixes
Most sync errors resolve themselves or take less than a minute to fix. SalesToBooks detects failures automatically and often fixes them before you even notice. But if you see a failed report on your dashboard, here's what to do.
Error: Expired OAuth Token
What it means: Your POS or accounting software connection expired. OAuth tokens have a limited lifespan and need to be refreshed.
How to fix:
- Go to Connections in the sidebar
- Find the connection showing "Disconnected" or "Token Expired"
- Click Reconnect
- Log in and re-authorize access
SalesToBooks tries to refresh tokens automatically. If automatic refresh fails, you'll get an email asking you to reconnect.
Error: Unmapped Categories
What it means: Your POS has categories that haven't been mapped to accounting accounts. This usually happens when you add new menu categories in your POS.
How to fix:
- Go to Connections → Mappings
- Look for categories showing "Unmapped"
- Select the right QuickBooks/Xero/FreshBooks account for each
- Save and retry the failed sync from the Reports page
Error: API Timeout
What it means: Your POS or accounting provider's API didn't respond in time. This is usually temporary — server load, maintenance, or network hiccups.
How to fix: Wait 15-30 minutes and retry from the Reports page. If it persists, our team is already investigating — you'll get an update via email.
Error: Duplicate Entry
What it means: An entry for this date already exists in your accounting software. This can happen if you manually created an entry or if a previous sync partially completed.
How to fix: Check your accounting software for the duplicate. Delete the manual entry if it exists, then retry the sync. SalesToBooks uses idempotency keys to prevent true duplicates on its end.
Error: Insufficient Permissions
What it means: The OAuth scope doesn't include the permissions SalesToBooks needs. This is rare but can happen if permissions were restricted during authorization.
How to fix: Disconnect and reconnect the affected provider. During re-authorization, make sure you approve all requested permissions.
Still Stuck?
Every failed sync creates an automatic support ticket on our end. A developer — not a support agent — investigates every failure. If you need immediate help, reach out via the chat widget or email support@salestobooks.com.