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