Zoho Books Troubleshooting

Common Issues

OAuth Authorization Failed

Symptoms: You are redirected back to autoGMS with an error after clicking Authorize.

Causes:

• Wrong Zoho region selected. Your account might be on .eu but you selected .com.
• Your Zoho Books subscription has expired.
• You do not have admin permissions in Zoho Books.

Fix: Disconnect the integration, verify your Zoho region at accounts.zoho.com, and reconnect with the correct region.

Sync Failed: Contact Not Found

Symptoms: Invoice sync fails with "contact not found in Zoho Books".

Cause: The customer was not synced before the invoice sync attempted. This can happen if the customer sync had an error.

Fix: Check the sync log for customer sync errors. Fix the customer record (usually a missing required field), then retry sync.

Sync Failed: Rate Limited

Symptoms: Sync errors with HTTP 429 status.

Cause: Zoho Books API rate limits (varies by plan, typically 100-150 requests per minute).

Fix: Wait a few minutes and retry. The sync engine has built-in retry logic with exponential backoff, so most rate limit errors resolve automatically.

Duplicate Records in Zoho

Symptoms: The same customer or invoice appears multiple times in Zoho Books.

Cause: A sync was interrupted and retried, or the integration was disconnected and reconnected without clearing sync state.

Fix: Delete the duplicates in Zoho Books manually. Ensure you do not disconnect and reconnect unless necessary.

Amounts Do Not Match

Symptoms: Invoice totals in Zoho Books differ from autoGMS.

Cause: Tax calculation differences. Zoho may round differently or apply tax rules that differ from the manual tax rate set in autoGMS.

Fix: Review tax settings in both systems. Ensure tax rates match exactly. Zoho Books recalculates totals from line items, so verify individual line amounts.

Token Refresh Failed

Symptoms: Integration shows "disconnected" or sync fails with authentication errors after working previously.

Cause: OAuth refresh token expired or was revoked in Zoho.

Fix: Disconnect and reconnect the integration to obtain fresh tokens.

Getting Help

If you cannot resolve an issue with the steps above, contact support with:

• The error message from the sync log.
• The entity type that failed (customer, invoice, etc.).
• Your Zoho Books region.