n8n Salesforce API Error Codes

Step by Step Guide to solve n8n Salesforce API Error Codes

 

---

 

Who this is for: Automation engineers who use n8n to integrate with Salesforce and need deterministic handling of API failures. We cover this in detail in the n8n API Integration Errors Guide.

---

Quick‑Fix Matrix

Error Code	HTTP Status
INVALID_FIELD	400
MALFORMED_QUERY	400
UNAUTHORIZED	401
INSUFFICIENT_ACCESS	403
REQUEST_LIMIT_EXCEEDED	429
SERVER_UNAVAILABLE	503
INVALID_SESSION_ID	401
DUPLICATE_VALUE	400
CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY	400
QUERY_TIMEOUT	408

Typical Trigger	Quick Fix
Field does not exist on the object	Verify the exact API name in Setup → Object Manager
SOQL syntax error	Test the query in Developer Console; escape reserved words
OAuth token missing or expired	Add a Refresh Token node or re‑authenticate the credential
Profile lacks CRUD permission	Grant Read/Write on the object or switch to an integration user
API‑call quota exceeded	Insert a Rate‑Limit node or batch with Delay
Salesforce service outage	Add exponential‑back‑off retry logic; monitor status.salesforce.com
Session revoked (e.g., password change)	Re‑authenticate; enable OAuth2 refresh flow
Unique‑field violation	Use Upsert or deduplicate before Create
Trigger/workflow blocks DML	Disable offending trigger or adjust its criteria
Long‑running SOQL query	Reduce selected fields, add selective filters

EEFA Note – Wrap every Salesforce node in a Try/Catch sub‑workflow that logs $node["Salesforce"].json to a persistent store. This preserves the raw errorCode needed for automated remediation.

---

1. Why Salesforce Returns Structured Error Codes in n8n

If you encounter any n8n google sheets api errors resolve them before continuing with the setup.

n8n forwards the raw JSON body from Salesforce’s REST API. The payload always contains:

{
  "errorCode": "INVALID_FIELD",
  "message": "No such column 'Foo__c' on entity 'Account'."
}

errorCode – Canonical identifier defined by Salesforce (stable across API versions).
message – Human‑readable description for logging; not reliable for programmatic handling.

n8n surfaces both fields in the node’s Error output, enabling precise branching.

---

2. Mapping Error Codes to n8n Design Patterns

If you encounter any n8n s3 upload error handling resolve them before continuing with the setup.

n8n Pattern	Relevant Error Code(s)	Recommended Node Setup
Conditional Branch (If)	INVALID_FIELD, MALFORMED_QUERY	Compare $node["Salesforce"].json.errorCode and route to a *Fix Field* sub‑workflow
Retry Loop (Loop + Delay)	REQUEST_LIMIT_EXCEEDED, SERVER_UNAVAILABLE, QUERY_TIMEOUT	Loop ≤ 3 attempts, delay = 2^attempt * 1000 ms
Token Refresh (OAuth2 Refresh)	UNAUTHORIZED, INVALID_SESSION_ID	Place before each Salesforce node; enable “Refresh on Failure”
Deduplication (Set + If)	DUPLICATE_VALUE	Run a *Search* node first; on duplicate, switch to *Upsert*

EEFA Warning – Never rely on a generic “catch‑all” (statusCode !== 200). Distinct error codes demand distinct remediation; swallowing them causes silent data loss.

---

3. Building a Robust “Insert Contact” Workflow

Below is a production‑ready n8n workflow that inserts a Contact and gracefully handles duplicates, token expiry, and rate limits. The JSON is split into logical 4‑line snippets for readability.

3.1 Trigger – runs every 5 minutes

{
  "name": "Trigger",
  "type": "n8n-nodes-base.cron",
  "parameters": { "cronExpression": "0 */5 * * * *" }
}

3.2 Salesforce Insert – creates the Contact

{
  "name": "Salesforce Insert",
  "type": "n8n-nodes-base.salesforce",
  "parameters": {
    "operation": "create",
    "object": "Contact",
    "additionalFields": {
      "Email": "={{$json.email}}",
      "FirstName": "={{$json.firstName}}",
      "LastName": "={{$json.lastName}}"
    }
  },
  "credentials": { "salesforceOAuth2Api": "Salesforce Credential" }
}

3.3 Error Router – detects duplicate records

{
  "name": "Error Router",
  "type": "n8n-nodes-base.if",
  "parameters": {
    "conditions": {
      "string": [
        {
          "value1": "={{$node[\"Salesforce Insert\"].json.errorCode}}",
          "operation": "contains",
          "value2": "DUPLICATE_VALUE"
        }
      ]
    }
  }
}

3.4 Upsert Contact – updates if duplicate exists

{
  "name": "Upsert Contact",
  "type": "n8n-nodes-base.salesforce",
  "parameters": {
    "operation": "upsert",
    "object": "Contact",
    "upsertKey": "Email",
    "additionalFields": {
      "FirstName": "={{$json.firstName}}",
      "LastName": "={{$json.lastName}}"
    }
  }
}

3.5 Log Failure – persists unexpected errors

{
  "name": "Log Failure",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "url": "https://mylogservice.example.com/err",
    "method": "POST",
    "jsonParameters": true,
    "options": {
      "body": {
        "error": "={{$node[\"Salesforce Insert\"].json}}"
      }
    }
  }
}

Workflow wiring – The Trigger feeds the Insert node. The Insert node’s main output connects to both the Error Router (for duplicate handling) and Log Failure (for successful inserts). The Error Router’s true branch points to Upsert Contact; the false branch can be extended with additional retry or alert logic.

---

4. Common Error Scenarios & Fix Checklists

Scenario	Error Code(s)	Root Cause	Fix Checklist
Field name typo	INVALID_FIELD	API name mismatch	• Open Setup → Object Manager → Fields & Relationships • Copy exact API name • Update node field mapping
SOQL syntax error	MALFORMED_QUERY	Missing commas, wrong relationship syntax	• Validate query in Developer Console • Escape reserved words with backticks (`\“) • Follow SELECT Id, Name FROM Account pattern
Permission issue	INSUFFICIENT_ACCESS, UNAUTHORIZED	Integration user lacks CRUD or required OAuth scopes	• Grant *Read/Write* on the object via profile/permission set • Ensure OAuth scopes include api and refresh_token
API limits hit	REQUEST_LIMIT_EXCEEDED	> 15 000 calls/24 h (or per‑license limits)	• Insert a Rate‑Limit node • Consolidate bulk operations using the **Salesforce Bulk** node
Session revoked	INVALID_SESSION_ID	Password change, IP range change, or manual revocation	• Re‑authenticate the credential • Enable **OAuth2 Refresh Token** flow in the connected app
Unique field conflict	DUPLICATE_VALUE	Duplicate external ID on insert	• Switch to **Upsert** • Pre‑check existence with a *Search* node
Trigger blocks DML	CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY	Apex trigger or workflow prevents operation	• Disable offending trigger or adjust its criteria
Long‑running query	QUERY_TIMEOUT	Inefficient SOQL (no filters, too many fields)	• Select only needed fields • Add selective WHERE clauses • Consider indexing the filter fields

EEFA Tip – For high‑volume integrations, prefer the **Bulk API** (up to 10 000 records per batch). Its error object (batchInfo) contains state and errorMessage fields you can poll for BULK_API_ERROR.

---

5. Debugging Checklist (Practical)

1. Capture raw payload – Add a **Set** node: errorPayload = $node["Salesforce"].json.
2. Log externally – Use an **HTTP Request** node to POST the payload to Datadog, Sentry, etc.
3. Validate credentials – Click **Test** in the credential dialog; confirm api scope is present.
4. Confirm API version – n8n defaults to v52.0; some codes (e.g., FIELD_CUSTOM_VALIDATION_EXCEPTION) differ across versions. Align with your org’s *API Version* setting.
5. Check field‑level security – Even with object access, FLS can trigger INVALID_FIELD.
6. Subscribe to Salesforce status – Add a **Webhook** node that alerts on 5xx responses from status.salesforce.com.

---

6. Frequently Asked Questions

Q: Does n8n expose the full list of Salesforce error codes?
A: Yes. Every code returned by the REST API is passed unchanged in the node’s *Error* output. Use the tables above as a starter; the official Salesforce docs enumerate all codes.

Q: Can I automatically retry on REQUEST_LIMIT_EXCEEDED?
A: Absolutely. Wrap the Salesforce node in a **Loop** node with a **Delay** (2^$index * 1000 ms) and set the loop condition to $node["Salesforce"].json.errorCode === "REQUEST_LIMIT_EXCEEDED".

Q: How do I differentiate UNAUTHORIZED from INVALID_SESSION_ID?
A: Both return HTTP 401, but errorCode distinguishes them. UNAUTHORIZED usually signals missing OAuth scopes; INVALID_SESSION_ID indicates an expired or revoked token.

Q: Is there a way to translate error codes to user‑friendly messages?
A: Yes. Create a **Set** node with a mapping object, then reference it via an expression:

{
  "INVALID_FIELD": "Check field names in your Salesforce object.",
  "MALFORMED_QUERY": "Review SOQL syntax."
}

Use {{ $json[ $node["Salesforce"].json.errorCode ] }} to retrieve the friendly text.

---

Conclusion

Salesforce’s structured errorCode values give you deterministic control inside n8n workflows. By:

1. Parsing the errorCode from the node’s Error output,
2. Routing each code to a purpose‑built sub‑workflow (conditional, retry, token refresh, or deduplication), and
3. Logging the raw payload for observability,

you eliminate silent failures, respect API limits, and keep integrations resilient in production. Apply the tables, snippets, and checklist above to any n8n‑Salesforce flow, and your automations will recover gracefully from the full spectrum of Salesforce API errors.