docs(salesforce): add INVALID_CROSS_REFERENCE_KEY FAQ for Update Record errors

[george-dilthey]

What changed

Added a new FAQ section "Why am I seeing an INVALID_CROSS_REFERENCE_KEY error when updating a Salesforce record?" to docs/salesforce-integration-faqs.md. The section explains that this error comes from Salesforce (not Clay), passes through to the cell unmodified, and is caused by one of three conditions: wrong object type ID prefix, deleted/merged record, or integration user lacking record-level write access. Each cause includes a targeted fix.

Why

An Intercom ticket from Miles Ross at Pacvue (Enterprise) asked why they were getting "invalid cross reference ID" errors in their Salesforce Update Record action. Fin didn't handle the conversation — it was escalated directly to a human (Bo Morin) who gave a detailed explanation. The existing docs/salesforce-integration-faqs.md had no entry for this error. Adding it so Fin can answer next time without escalation.

The support agent's explanation explicitly covered all three causes, and the customer said "Thanks!" then immediately asked to close the ticket — strong signal the answer fully addressed the question. Multiple other enterprise customers have hit the same error (corroborating Slack threads below).

Source link(s)

• Intercom conversation: https://app.intercom.com/a/inbox/w28k1kwz/inbox/conversation/215475628322076
• Slack trigger thread (ent-pacvue-clay): https://clay-hq.slack.com/archives/C0ARKGC0WUD/p1787612451944929
• Support agent reply with the three-cause explanation: https://clay-hq.slack.com/archives/C0ARKGC0WUD/p1787613019103289
• Verifier sub-agent: PASS — public-actions/apps/salesforce-new-ui/actions/update-object/action-code.ts:212-223 confirms Clay extracts .message fields from Salesforce's error array and returns them to the cell without wrapping (INVALID_CROSS_REFERENCE_KEY has no special-case branch; only UNABLE_TO_LOCK_ROW is intercepted by name). Action definition: isPublic: true, no Eppo/LaunchDarkly gate — available to all users. All three stated causes verified against code and corroborating Slack threads (#proj-audience-import-export Apr 2026 confirming deleted-record cause; #team-audiences Aug 2026 showing the same error in a different context).

Uncertainties

None. Cause 3 (sharing rules/ownership) is technically a slight simplification — Salesforce sometimes returns INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY for pure permission denials, but returns INVALID_CROSS_REFERENCE_KEY when the record is invisible to the integration user (indistinguishable from non-existence from the user's perspective). The description is functionally accurate for customer self-service troubleshooting, and matches how Clay's own support agents explain it to customers.

Related observations

None.

Closes DOC-2054

[linear-code]

DOC-2054