n8n Salesforce API Error Codes

n8n API Integration Errors / 2 Comments

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.

Must Read

2 thoughts on “n8n Salesforce API Error Codes”

  1. Mathematical soccer betting tips

    Very insightful post! I’ve been researching how statistical models like the Kara model can outperform traditional betting methods.
    Integrating ELO ratings and ROI analysis is definitely the future of football
    predictions. If anyone is interested in seeing how data-driven tips work in practice, I’ve been tracking some very interesting results lately.
    Keep up the good work!

    Reply
  2. Dewa99

    Wonderful put up, veгy informative.
    I wonder whу the opposite spеcialists of this sector do not reaⅼіze
    thiѕ. You should proceed your writing. I am sure,
    you’ve a great readers’ base already!

    Reply

Leave a Comment

Your email address will not be published. Required fields are marked *