## 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.

```text
salesforce 400 INVALID_FIELD duplicate rule blocked lead insert
```

## Use 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
1. Read the error to confirm a duplicate rule, not a validation rule, blocked the insert. Verify: the message references duplicate detection.
2. 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.
3. 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.
4. For bulk loads, pre-dedupe the file against existing records before sending. Verify: a rerun of the batch inserts zero conflicts.
5. 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