# Common Issues
## Connection issues
"Invalid API token" or "Unauthorized" error
Your API token has expired or doesn't have the right permissions. Regenerate it in Zoho CRM:
1. Go to **Settings** → **APIs** → **API Tokens** (or **OAuth Tokens** depending on your Zoho CRM version)
2. Delete the old token and click **Create Token**
3. Select the scope **ZohoCRM.modules.READ** for read-only access to all modules
4. Copy the new token and paste it into Coupler.io
5. Test the connection with a manual run
If you're using OAuth instead of API tokens, make sure your Coupler.io integration is authorized and your Zoho account hasn't revoked access.
"Invalid environment or base URL" error
You've selected an environment (Production, Developer, or Sandbox) that doesn't match your Zoho CRM setup. Check which environment your account uses:
* **Production**: The main Zoho CRM account you use daily
* **Developer**: Your free Zoho developer sandbox (only available if you signed up for a developer account)
* **Sandbox**: A test environment (available on Enterprise and Ultimate plans)
Select the correct environment in Coupler.io and retry.
Connection times out or hangs
This can happen if your Zoho CRM account has millions of records or your network is slow. Try:
1. Set a **Start date** to limit data export to the last 30–90 days instead of syncing all historical data
2. Reduce the number of modules or fields you're syncing in the first run
3. Test with a single module (e.g., Leads) before adding multiple modules
4. Wait 5–10 minutes and retry; Zoho's API may be temporarily throttled
## Missing data
Some records or modules don't appear in the destination
Check if:
1. **Your API token scope is correct**: The token must have **ZohoCRM.modules.READ** permission. Tokens with limited scopes (e.g., only Leads access) won't fetch all modules.
2. **The module is visible in your Zoho CRM**: Some custom modules may be hidden or restricted by admin settings. Verify the module appears when you log into Zoho CRM.
3. **Your start date is too recent**: If you set a start date after the records were created, they won't sync. Clear the start date or set it earlier.
4. **Field-level permissions**: If your Zoho CRM admin restricted certain fields, they may not appear in the export. Contact your admin to grant field-level read access.
Deal or Contact records are missing related Account data
Zoho CRM stores related records as lookup field IDs, not full nested data. To get Account details alongside Deals or Contacts:
1. Create a **Join** transformation in Coupler.io
2. Join the Deals table to the Accounts table on the Account ID field
3. Select which Account fields (name, industry, revenue) you want to include
This merges both datasets so you see Account information for every Deal.
Custom field data is empty or shows as "null"
Custom fields may not sync if:
1. **The field is restricted by admin permissions**: Your Zoho admin may have hidden the field from API access. Ask your admin to enable API access for that field.
2. **The field isn't populated for all records**: If only some records have values in that custom field, others will appear blank — this is expected.
3. **The field type isn't supported**: Zoho CRM supports most field types in API exports; if it's a very new or proprietary field type, contact Coupler.io support.
## Permission errors
"You don't have permission to access this module" error
Your Zoho CRM user role doesn't have read access to that module. Ask your Zoho CRM admin to:
1. Go to **Setup** → **Users & Roles** → **Roles**
2. Select your role and check the **Module Permissions** section
3. Enable **Read** access for the modules you need to sync
4. Re-test the connection in Coupler.io
API token was revoked by admin
If your Zoho CRM admin revoked the token (e.g., during a security audit), you'll see an "Unauthorized" error. Generate a new API token:
1. Go to **Settings** → **APIs** → **API Tokens**
2. Click **Create Token** and select the appropriate scope
3. Update the token in Coupler.io and test again
## Data discrepancies
Record counts don't match between Zoho CRM and Coupler.io destination
This can happen for a few reasons:
1. **Time zone differences**: Zoho CRM stores all dates in UTC. If you set a start date, records created near midnight in your time zone may fall on different sides of the UTC boundary. Use a date range with a few days of buffer.
2. **Duplicate records**: If Coupler.io isn't set to replace old data (it appends by default), you may see duplicates on subsequent runs. Check your data flow settings and enable **Replace** mode if needed.
3. **Soft-deleted records**: Zoho CRM may include records marked as deleted or archived. If Coupler.io's destination uses **Append** mode, these may appear alongside active records.
4. **Filters or field-level security**: Your Zoho admin may have filtered records or restricted certain fields, reducing the data Coupler.io can access.
Deal amounts or other numeric fields show as text or zero
Zoho CRM's API sometimes returns numeric fields as text strings. In your destination:
* **Google Sheets**: Format the column as **Number** and use `=VALUE()` to convert if needed
* **Excel**: Use **Format Cells** → **Number** or apply a formula like `=VALUE(A1)`
* **BigQuery**: Cast the column as `CAST(field AS FLOAT64)`
Alternatively, set up a transformation in Coupler.io if the source data is consistently mistyped.
## Rate limits
"Rate limit exceeded" or "Quota exceeded" error
Zoho CRM's API rate limits depend on your edition:
* **Free**: 100 API calls/minute
* **Standard**: 1,000 API calls/minute
* **Professional & up**: Significantly higher; see Zoho's documentation
If you hit the limit:
1. **Wait 1 minute** before retrying — the quota resets per minute
2. **Reduce batch size**: Sync fewer modules or fields per data flow
3. **Stagger schedules**: If you have multiple Coupler.io data flows, schedule them 10–15 minutes apart so API calls don't pile up
4. **Consider upgrading**: If you consistently hit limits, upgrading your Zoho CRM edition increases your quota
Scheduled data flow fails intermittently
Intermittent failures often indicate hitting rate limits during peak hours. Try:
1. **Schedule the data flow for off-peak hours** (early morning or late evening in your time zone)
2. **Increase refresh interval**: Instead of hourly syncs, switch to every 6 hours or daily
3. **Reduce data scope**: Sync only the essential modules and fields
4. **Check Zoho's system status**: Zoho CRM may have maintenance windows that temporarily limit API availability