salesforce 400 INVALID_FIELD duplicate rule blocked lead insert
Gets leads past Salesforce duplicate rules that block inserts with a 400 INVALID_FIELD error: dedupe before insert or allow the save explicitly. Use when Lead inserts fail citing a duplicate rule match. Not for validation rule failures, which cite the validation rule instead.
TL;DR
An active duplicate rule matched the incoming lead and blocked the insert. Check for the existing record first, merge instead of insert, or pass the duplicate-rule header to allow the save when your process intentionally allows dupes.
salesforce 400 INVALID_FIELD duplicate rule blocked lead insertUse this when
- Lead insert returns 400 with INVALID_FIELD and a duplicate rule message.
- A bulk lead load dies on a handful of records.
- The rule fires on records that look unique to the sender.
Not for this skill when
- Validation rule errors, which name the validation rule.
- Required-field missing errors.
- Duplicate rule warnings that allow save, which are not errors.
Steps
- Read the error to confirm a duplicate rule, not a validation rule, blocked the insert. Verify: the message references duplicate detection.
- Find the matching existing lead with a SOQL query on the rule's matching fields. Verify: you can see the existing record that triggered the match.
- Decide per record: update the existing lead, or merge the data into it. Verify: the merge logic is written down and tested on one record.
- For bulk loads, pre-dedupe the file against existing records before sending. Verify: a rerun of the batch inserts zero conflicts.
- If the process legitimately needs duplicates, set the duplicate-rule header to allow save on that integration user. Verify: the insert succeeds and the duplicate is logged.
Variant phrasings
salesforce duplicate rule blocked insert
Common phrasing of the block.
salesforce lead insert duplicate detected 400
The code-angle search.
duplicate rule header allow save salesforce
The header-angle search.
Compatibility: Salesforce REST and SOAP APIs; duplicate rules configured per object in setup.
Why it happens
Duplicate rules exist to keep the database clean; they run on every insert and match on fields like email, name, and phone. Agent-built integrations that insert without checking first hit the rule constantly, especially on re-runs.
Edge cases / pitfalls
- Matching is fuzzy by default; near-matches you consider distinct will still fire.
- The header choice applies per request; a second code path without it still blocks.
- Bypass permissions on the integration user defeat the rule silently; scope them tightly.
- Reporting on blocked saves needs the duplicate error objects; log them, do not swallow.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_KXGkAFEVRxPznlIKeKjT3A