Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(zoho-crm): tell users to exchange the self client code for a refresh token (#118400)

Tom Owers7b7fb437c8f5
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/source.py
index fe84f6f57e4a..4e12408b5ac7 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/source.py
@@ -31,6 +31,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.s
)
from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.zoho_crm import (
REFRESH_TOKEN_REJECTED_MESSAGE,
+ TOKEN_ERROR_MESSAGES,
+ TOKEN_REFRESH_FAILED_PREFIX,
ZohoCRMResumeConfig,
validate_credentials as validate_zoho_crm_credentials,
zoho_crm_source,
@@ -74,7 +76,8 @@ class ZohoCRMSource(ResumableSource[ZohoCRMSourceConfig, ZohoCRMResumeConfig]):
def get_non_retryable_errors(self) -> dict[str, str | None]:
return {
- "Zoho CRM token refresh failed": REFRESH_TOKEN_REJECTED_MESSAGE,
+ **{f"{TOKEN_REFRESH_FAILED_PREFIX}: {code}": message for code, message in TOKEN_ERROR_MESSAGES.items()},
+ TOKEN_REFRESH_FAILED_PREFIX: REFRESH_TOKEN_REJECTED_MESSAGE,
"400 Client Error: Bad Request for url: https://accounts.zoho": "Zoho CRM rejected your OAuth credentials. Check that the client ID, client secret, and refresh token all belong to the same self client.",
# Some responses carry no reason phrase (e.g. over HTTP/2, which has none), so
# `requests.raise_for_status()` renders it blank instead of "Bad Request" — match that
@@ -95,7 +98,7 @@ class ZohoCRMSource(ResumableSource[ZohoCRMSourceConfig, ZohoCRMResumeConfig]):
releaseStatus=ReleaseStatus.ALPHA,
caption="""Connect your Zoho CRM account to pull leads, contacts, deals, and your other modules into the PostHog Data warehouse.
-In the [Zoho API console](https://api-console.zoho.com), create a **Self Client** and generate a refresh token for the scopes `ZohoCRM.modules.ALL`, `ZohoCRM.settings.fields.READ`, and `ZohoCRM.settings.modules.READ`. Paste the client ID, client secret, and refresh token below, then pick the data center your Zoho account lives in.""",
+In the [Zoho API console](https://api-console.zoho.com), create a **Self Client** and generate a code for the scopes `ZohoCRM.modules.ALL`, `ZohoCRM.settings.fields.READ`, and `ZohoCRM.settings.modules.READ`. That code is not a refresh token and expires within minutes. Exchange it for a refresh token by sending a POST request to `/oauth/v2/token` on your data center's Zoho accounts domain, with `grant_type=authorization_code`, your client ID, client secret, and the code. Paste the client ID, client secret, and refresh token below, then pick the data center your Zoho account lives in.""",
iconPath="/static/services/zoho_crm.png",
docsUrl="https://posthog.com/docs/cdp/sources/zoho-crm",
fields=cast(
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm.py b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm.py
index f5437fecdfc5..118f63a637ce 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm.py
@@ -23,6 +23,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_
)
from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.source import ZohoCRMSource
from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.zoho_crm import (
+ CLIENT_REJECTED_MESSAGE,
+ CLIENT_SECRET_REJECTED_MESSAGE,
MAX_FIELDS_PER_REQUEST,
MAX_PAGE,
PAGE_SIZE,
@@ -319,15 +321,21 @@ class TestValidateCredentials:
assert is_valid is False
assert error is not None and "mars" in error
- def test_refresh_token_rejection_gives_actionable_copy(self) -> None:
- # The raw Zoho OAuth error code (here "invalid_client") is not actionable, so validation
- # must return the friendly reconnect message instead of leaking the code.
- with scripted_network(_script([], tokens=[_response(200, {"error": "invalid_client"})])):
+ @pytest.mark.parametrize(
+ ("error_code", "expected"),
+ [
+ ("invalid_code", REFRESH_TOKEN_REJECTED_MESSAGE),
+ ("invalid_client", CLIENT_REJECTED_MESSAGE),
+ ("invalid_client_secret", CLIENT_SECRET_REJECTED_MESSAGE),
+ ],
+ )
+ def test_token_rejection_gives_actionable_copy(self, error_code: str, expected: str) -> None:
+ with scripted_network(_script([], tokens=[_response(200, {"error": error_code})])):
is_valid, error = validate_credentials("us", "cid", "secret", "refresh")
assert is_valid is False
- assert error == REFRESH_TOKEN_REJECTED_MESSAGE
- assert "invalid_client" not in (error or "")
+ assert error == expected
+ assert error_code not in (error or "")
def test_http_failure_is_not_valid(self) -> None:
with scripted_network(_script([_response(403)])):
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm_source.py
index 86d5e82eb843..52eee7d6e3c0 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm_source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/tests/test_zoho_crm_source.py
@@ -10,7 +10,10 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_
from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.settings import ZOHO_CRM_ENDPOINTS
from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.source import ZohoCRMSource
from products.warehouse_sources.backend.temporal.data_imports.sources.zoho_crm.zoho_crm import (
+ CLIENT_REJECTED_MESSAGE,
+ CLIENT_SECRET_REJECTED_MESSAGE,
REFRESH_TOKEN_REJECTED_MESSAGE,
+ ZohoCRMAuthError,
ZohoCRMResumeConfig,
)
@@ -116,3 +119,21 @@ class TestZohoCRMSource:
self.source.source_for_pipeline(self.config, mock.MagicMock(), inputs)
assert mock_source.call_args.kwargs["db_incremental_field_last_value"] is None
+
+
+ ("error_code", "expected"),
+ [
+ ("invalid_code", REFRESH_TOKEN_REJECTED_MESSAGE),
+ ("invalid_client", CLIENT_REJECTED_MESSAGE),
+ ("invalid_client_secret", CLIENT_SECRET_REJECTED_MESSAGE),
+ (None, REFRESH_TOKEN_REJECTED_MESSAGE),
+ ],
+)
+def test_sync_token_failure_shows_the_message_for_its_error_code(error_code: str | None, expected: str) -> None:
+ error = str(ZohoCRMAuthError(error_code)).lower()
+ friendly = [
+ message for pattern, message in ZohoCRMSource().get_non_retryable_errors().items() if pattern.lower() in error
+ ]
+
+ assert friendly[0] == expected
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/zoho_crm.py b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/zoho_crm.py
index 9796ba84ab1f..1e9c94cefa05 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/zoho_crm.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/zoho_crm/zoho_crm.py
@@ -63,12 +63,33 @@ REQUEST_TIMEOUT_SECONDS = 60
# Shown when the refresh-token exchange is rejected. The raw Zoho `error` code (e.g. `invalid_code`)
# is kept on the exception for logs but never surfaced to users, who can't act on it.
REFRESH_TOKEN_REJECTED_MESSAGE = (
- "Zoho CRM rejected your refresh token. Generate a new one for your self client and reconnect."
+ "Zoho CRM rejected your refresh token. Exchange a new code from your self client's Generate Code tab "
+ "for a refresh token, then reconnect."
)
+# Zoho also answers `invalid_client` for a client registered in another data center.
+CLIENT_REJECTED_MESSAGE = (
+ "Zoho CRM doesn't recognize this client in the data center you picked. Check the client ID and secret, "
+ "and pick the data center your Zoho account uses."
+)
+CLIENT_SECRET_REJECTED_MESSAGE = (
+ "Zoho CRM rejected your client secret. Copy it again from your self client, then reconnect."
+)
+# `invalid_client_secret` comes first because error patterns match as substrings.
+TOKEN_ERROR_MESSAGES = {
+ "invalid_client_secret": CLIENT_SECRET_REJECTED_MESSAGE,
+ "invalid_client": CLIENT_REJECTED_MESSAGE,
+}
+TOKEN_REFRESH_FAILED_PREFIX = "Zoho CRM token refresh failed"
class ZohoCRMAuthError(Exception):
- pass
+ def __init__(self, error_code: Optional[str]) -> None:
+ super().__init__(f"{TOKEN_REFRESH_FAILED_PREFIX}: {error_code or 'no access token returned'}")
+ self.error_code = error_code
+
+ @property
+ def user_message(self) -> str:
+ return TOKEN_ERROR_MESSAGES.get(self.error_code or "", REFRESH_TOKEN_REJECTED_MESSAGE)
@dataclasses.dataclass
@@ -169,7 +190,7 @@ class ZohoCRMClient:
access_token = body.get("access_token")
if not access_token:
# Zoho answers a revoked or malformed refresh token with HTTP 200 and an `error` key.
- raise ZohoCRMAuthError(f"Zoho CRM token refresh failed: {body.get('error') or 'no access token returned'}")
+ raise ZohoCRMAuthError(body.get("error"))
api_domain = body.get("api_domain")
if api_domain:
@@ -373,8 +394,8 @@ def validate_credentials(
try:
client.get(f"/crm/{api_version}/settings/modules")
- except ZohoCRMAuthError:
- return False, REFRESH_TOKEN_REJECTED_MESSAGE
+ except ZohoCRMAuthError as e:
+ return False, e.user_message
except Exception:
return False, None
return True, None