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.
Most Sync Errors Are Quick Fixes
When a sync fails, our monitoring catches it within seconds and often resolves it before you notice. But if you see a failed report on your dashboard, here's what's probably going on and how to fix it.
Error: Expired OAuth Token
What it means: Your POS or accounting connection expired. OAuth tokens don't last forever and sometimes automatic refresh fails.
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. When automatic refresh fails, you'll get an email asking you to reconnect — it takes about 30 seconds.
Error: Unmapped Categories
What it means: Your POS has categories that don't have a corresponding accounting account mapped yet. This usually happens when you add a new menu category in your POS.
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. Usually temporary — server load, maintenance, or network issues on their end.
Fix: Wait 15-30 minutes and retry from the Reports page. If it keeps happening, we're already looking into it and you'll get an email when it's resolved.
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 a previous sync partially completed.
Fix: Check your accounting software for the duplicate. Delete the manual entry, then retry the sync. SalesToBooks uses idempotency keys to prevent duplicates on its side — the issue is almost always a manually created entry.
Error: Insufficient Permissions
What it means: The OAuth connection doesn't include all the permissions SalesToBooks needs. Rare, but it happens if permissions were restricted during authorization.
Fix: Disconnect and reconnect the affected provider. During re-authorization, make sure you approve all requested permissions.
Still Stuck?
Every failed sync creates a ticket on our end automatically. A developer — the person who built the sync code — investigates every failure. If you need help right now, use the chat widget or email support@salestobooks.com.