Gå til innholdet
SteveTechArcSteveTechArc Courses

What You'll See When It Breaks

Dette innholdet er ikke tilgjengelig på ditt språk.

Module 6 of 6 in the chapter The Admin’s Integration Toolkit, chapter 4 of the Integration Architect course. Each module stands on its own. Previous: Platform Events in Flow · Next: the chapter overview, The Admin’s Integration Toolkit

The question this module answers: When an integration breaks, what does an admin actually see, and where do you look first?

When you’re doing integrations, you need to be thinking about how you’re going to handle errors. Everyone knows the error email that arrives in the admin’s inbox. It’s kind of useless sometimes, but it’s one way to find out. Plan for Failure, in chapter 1, asked what failure costs. This module is the admin’s side of it: four things you’ll see with this chapter’s toolkit, what each one means, and where to look first.

Read the Status First

Section titled “Read the Status First”

The first thing you’ll see is a callout that failed. Every time there’s a callout, you have to handle the errors, so every callout action gets a fault path. In module 3 we saw that Salesforce treats “a response status code of 300 or greater” as an error and sends the flow down the fault path (HTTP Callout Considerations and Limits (opens in a new tab), Salesforce Help, checked 2026-11-01).

On the fault path, keep what went wrong. The flow’s fault message, {!$Flow.FaultMessage}, holds the error (Configure Every Fault Path to Send You an Email (opens in a new tab), Salesforce Help, checked 2026-11-01). Save it to a log record, or publish it as an error event for one central error-handling flow, as in module 5. Then read the status, because it tells you where to look before any log does. You know the codes from chapter 3: the 400s are the client’s to fix, the 500s the server’s. With this chapter’s toolkit, the 400s point to two different places:

  • The gate: 401 and 403. A 401 is “who are you?”: the sign-in failed. Going out, check the named credential and its external credential, and that the flow’s user has the permission set for the principal (module 1). A 403 is “I know who you are, and it’s not for you”: the access is missing. And when it’s Salesforce turning Redrock away, the same two gates apply: check the External Client App’s scopes and the integration user’s permissions (module 4).
  • The request: 400 and 404. A 400 means the request makes no sense to Redrock: the shape is wrong, often because the sample or the spec no longer matches what Redrock expects (module 2, module 3). A 404 means no such address, or no such record: Redrock has never heard of delivery D-1042.
  • The other side: the 500s, and “not now.” A 500 is broken on Redrock’s side. A 503, or no answer at all, is “not now.” So is a 429, “too many requests”: it’s a 400, but the request isn’t wrong, it’s just too soon. There’s nothing to fix in your flow. Wait, try again later, and tell Redrock.

Which ones do you try again? Salesforce’s Well-Architected guidance matches the error to the answer (Reliability (opens in a new tab), Salesforce Architects, checked 2026-11-01). For a 429, wait as long as the other system tells you to. For the 500s, try again, waiting longer each time: one second, then two, four, eight, up to a limit. For the other 400s: “Don’t retry; fix the request.” Sending the same wrong request again only gets the same answer. Every standard code, with whose it is to fix and whether to try again, is in the HTTP Status Codes reference.

Read the status first Three panels: where a failing call points. The gate, in amber, 401 and 403: 401, who are you, the sign-in failed; 403, not for you, the access is missing; check the credential and the user; ours to fix. The request, in amber, 400 and 404: 400, the request makes no sense; 404, no such address or record; check the shape, the path and the ID; ours to fix. The other side, in coral, 500, 503, 429 or no answer: 500, it broke on their side; 503, 429 or no answer, not now; wait longer each time, and tell them; theirs to fix. Underneath: every callout gets a fault path; read the status before you read the logs. {"author": "Steve Simpson", "blueprint": "1.0.0", "builder": "standard 1.52.0", "built": "2026-10-29", "id": "DGM-INT-AT-14", "rights": "\u00a9 2026 Twinshark LLC. All rights reserved.", "template": "comparison/side-by-side 0.5.0", "theme": "stevetecharc 1.4.0"} The gate 401, 403 401: who are you? The sign-in failed 403: not for you. The access is missing Check the credential and the user Ours to fix The request 400, 404 400: the request makes no sense 404: no such address or record Check the shape, the path, the ID Ours to fix The other side 500, 503, 429, no answer 500: it broke on their side 503, 429 or no answer: not now Wait longer each time; tell them Theirs to fix Every callout gets a fault path. Read the status before you read the logs. © 2026 Twinshark LLC · stevetecharc.com
Click to enlarge

Read the status first.

A Fault Path Changes What’s Saved

Section titled “A Fault Path Changes What’s Saved”

Here’s the one that surprises people. Adding a fault path doesn’t only change what the user sees. It changes what gets saved.

Take Steve Trucking’s record-triggered flow on the delivery. Salesforce describes both cases (Default Flow Error Handling (opens in a new tab), Salesforce Help, checked 2026-11-01):

  • With no fault path, when an element fails, Salesforce “blocks the triggering change and rolls back the transaction.” The person saving the delivery sees “An unhandled fault has occurred in this flow.” Salesforce creates a failed interview and sends the fault email.
  • With a fault path, Salesforce “doesn’t block the triggering change. The flow runs the fault path, and Salesforce doesn’t roll back the transaction.” The person sees an error only if the fault path includes an Error element.

So with a fault path, the delivery is saved, even though what failed didn’t happen. Most of the time that’s what you want: a late delivery is still late, whether or not Redrock heard about it. But it’s a decision. If the record shouldn’t be saved when the step fails, the fault path has to say so, with an Error element. And when the record is saved, the fault path is the only record that something went wrong, so make it log the error.

A fault path changes what's saved Two panels: what happens when an element fails in a record-triggered flow. No fault path, in coral: Salesforce blocks the change; the save is rolled back; the user sees "an unhandled fault has occurred"; a failed interview and a fault email. With a fault path, in blue: the change is saved; the flow runs the fault path; nothing is rolled back; the user sees an error only with an Error element. Underneath: a fault path doesn't undo the save; decide what happens to the record, and log what went wrong. {"author": "Steve Simpson", "blueprint": "1.0.0", "builder": "standard 1.52.0", "built": "2026-10-29", "id": "DGM-INT-AT-16", "rights": "\u00a9 2026 Twinshark LLC. All rights reserved.", "template": "comparison/side-by-side 0.5.0", "theme": "stevetecharc 1.4.0"} No fault path the flow stops Salesforce blocks the change The save is rolled back The user sees: an unhandled fault A failed interview and a fault email With a fault path the flow goes on The change is saved The flow runs the fault path Nothing is rolled back An error shows only with an Error element A fault path doesn't undo the save. Decide what happens to the record, and log what went wrong. © 2026 Twinshark LLC · stevetecharc.com
Click to enlarge

A fault path changes what’s saved.

Uncommitted Work Pending

Section titled “Uncommitted Work Pending”

The second thing you’ll see is a flow that fails before it calls anyone, with an error that says you have uncommitted work pending, and to commit or roll back before calling out.

Here’s why. You cannot write something and then make a callout in the same transaction. Salesforce wants to commit the save or roll it back, and it’s not going to hold the save open while it waits for another system to answer. So you can call out and then write. But you can’t write and then call out.

That’s easy to hit in a record-triggered flow. The flow runs while the delivery is being saved, so a callout there comes after a write. The fix is the one from module 3: put the callout on the asynchronous path, which runs “after the original transaction for the triggering record is successfully committed” (Connect a Record-Triggered Flow to an External System Using an Asynchronous Path (opens in a new tab), Salesforce release notes, checked 2026-11-01). Write now, and call later, in a transaction of its own.

Salesforce has also made this easier. Since Winter ‘26, an action that makes a callout has a transaction control setting, under its Advanced settings. Let the flow decide, which Salesforce recommends, means that “if this action involves a callout, and the current transaction has pending operations, the current transaction is committed before running the action in a new transaction” (How Flows Run in Transactions (opens in a new tab), Salesforce Help, checked 2026-11-01). Three things to know:

  • Older actions don’t do it by default. An action configured in Summer ‘25 or earlier is set to Always continue in current transaction, and then the flow fails. Salesforce recommends changing those to Let the flow decide.
  • In a record-triggered flow, it works only on an asynchronous or scheduled path, not on the path that runs immediately. So the asynchronous path is still the fix there.
  • Debugging behaves differently. “When debugging the flow, the action always runs in the current transaction and can cause an error if there are callouts.” So a callout can fail when you debug the flow and work when it runs for real.
Write, then call out: not in one go Three panels. Write, then call out, in one transaction, in coral: the record is saved but not yet committed; the callout would hold it open; Salesforce stops it, with the error that there's uncommitted work pending. Call out, then write, in one transaction, in green: read or query first if you need to; make the callout; then save what came back; it works. Write, then call out later, on the asynchronous path, in green: the record is saved and committed; a new transaction starts; it makes the callout; it works. Underneath: you can call, then write; you can't write, then call; or write now and call later. {"author": "Steve Simpson", "blueprint": "1.0.0", "builder": "standard 1.52.0", "built": "2026-10-29", "id": "DGM-INT-AT-15", "rights": "\u00a9 2026 Twinshark LLC. All rights reserved.", "template": "comparison/side-by-side 0.5.0", "theme": "stevetecharc 1.4.0"} Write, then call out in one transaction The record is saved, not yet committed The callout would hold it open Salesforce stops it Uncommitted work pending Call out, then write in one transaction Read or query first, if you need to Make the callout Then save what came back Works Write, then call out later the asynchronous path The record is saved and committed A new transaction starts It makes the callout Works You can call, then write. You can't write, then call. Or write now and call later. © 2026 Twinshark LLC · stevetecharc.com
Click to enlarge

Call, then write; or write now and call later.

One thing changes when you split them: the save and the callout no longer succeed or fail together. The delivery is saved even if Redrock never hears about it. So you need really good error handling on the asynchronous path: a fault path, a log, and someone who reads it. Code has other ways to split them; chapter 9 shows them.

The Token That Went Quiet

Section titled “The Token That Went Quiet”

The third thing you’ll see is an integration that worked for months and then, one day, fails at sign-in. The answer from Salesforce’s token endpoint looks like this (Enforce One-Time-Use Refresh Tokens with Refresh Token Rotation (opens in a new tab), Salesforce Help, published 2026-10-21, checked 2026-11-01):

{"error":"invalid_grant","error_description":"expired access/refresh token"}

Often nothing is broken. Something sat unused. A refresh token is what lets a program keep signing in while nobody’s there, and “Salesforce requires a 30-day limit to the idle refresh token TTL (time-to-live)”: the time a refresh token can sit unused before it expires (Limit the Idle Refresh Token TTL in External Client Apps (opens in a new tab), Salesforce Help, checked 2026-11-01). Salesforce enforces it for External Client Apps; for older connected apps it’s a setting you turn on. It works as a sliding window: each time the token is used, the 30 days start again. An integration that runs every day never notices. One that runs once a quarter will fail every time.

Say Steve Trucking’s quarterly audit tool signs in to Salesforce with a refresh token. It runs in January and works. It runs in April and gets invalid_grant. Trying again won’t help. Salesforce’s advice is to catch this error and “initiate a fresh authentication flow rather than repeatedly retrying with the same invalid token.” So the fix today is for someone to authorize the tool again. The better fix is in the design:

  • Use a flow with no refresh token, where you can. The client credentials flow from module 4 has no refresh token to go quiet; the program signs in fresh and gets a new token each time it runs.
  • Watch the run, not only the errors. A job that didn’t run sends no error. It could easily have something going wrong, and if no one knows about it, it won’t work when it needs to work. Know when each integration should run, and notice when it didn’t.

Chapter 12 covers token lifetimes in full, and chapter 13 the once-a-quarter job.

The Flow That Never Ran

Section titled “The Flow That Never Ran”

The fourth thing is the hardest to see, because you see nothing. From module 5, in Salesforce’s words: “If an event fails, the flow doesn’t start. Because the flow is never triggered, a flow error email isn’t sent” (Subscribe to Platform Event Messages with Flows (opens in a new tab), checked 2026-11-01).

No email, no failed interview, no record. If the customer team stops hearing about late deliveries, nobody will tell you why. That’s the same lesson as the quiet token: for anything that matters, check that it happened, not only that nothing failed.

Where to Look First

Section titled “Where to Look First”

When something does break, here’s the order I use.

  1. Read the status and the fault message. It tells you which side, and which gate.
  2. Replicate it. Take the same request into your API client, from chapter 2, and send it the same way. For a call coming in, sign in the way Redrock does, through an External Client App in a sandbox, as an integration user, and send what Redrock sends. Does it fail the same way? Then it’s not the flow.
  3. Turn on debug logs, on the right user. Not on a busy integration user. If that user is being called five times a second, you get a flood of logs, you’re looking for one error in a sea of them, and the logs fill up fast. Instead, use a second user with the same permissions, turn its debug logs on, and replicate the call there. Never share the integration user’s own sign-in to do it.
  4. Look at what Salesforce kept. Your developer console, your debug logs, and the error emails. For flows, the failed interviews are on the Monitor tab of the Automation app, with the reason for each (Monitoring and Managing Paused and Failed Flow Interviews (opens in a new tab), checked 2026-11-01). And the flow error email goes “to the admin who last modified the process or flow,” unless you send it to the Apex exception email recipients instead (Customize What Happens When a Flow Fails (opens in a new tab)). Is that the person who should get it?

And mask before you look. Debug logs and payloads hold real deliveries, customers and sometimes secrets. Know what’s in a payload before you log it.

What an Architect Decides Here

Section titled “What an Architect Decides Here”
  • A fault path on every callout, and where its message goes: a log record, an error event, a person.
  • For each fault path: should the record still be saved when the step fails?
  • Which errors are tried again, how long to wait, and when to stop.
  • Which older flow actions still need Let the flow decide.
  • For each error code, who acts: the admin, the integration’s owner, or the other company.
  • Which callouts run on the asynchronous path, and how you’ll know when one fails after the save.
  • For every integration that signs in to Salesforce: does it use a refresh token, and does it run often enough to keep it?
  • How you’ll notice an integration that didn’t run, not only one that failed.
  • Which user you debug as, and what you mask.
  • Who gets each flow’s error email.

Beyond the exam: what AI changes. AI is good at reading an error. Give it the status, the fault message and the request, and it will often tell you which gate failed. But only give it what’s safe: a made-up or masked payload, and never a token, a secret or a real customer’s data. And AI can watch for the quiet failures too, if someone tells it what normal looks like: how often each integration should run. Chapter 13 goes further.

Explore

Section titled “Explore”

Følg meg

© 2023–2026 Twinshark LLC. All rights reserved. · Bruk av innholdet

Privacy notice

SteveTechArc is independent and is not affiliated with, sponsored by, or endorsed by Salesforce, Inc. Salesforce and related marks are trademarks of Salesforce, Inc.

Educational content, shared as is. Not professional, legal or financial advice. Salesforce changes several times a year, so check current Salesforce documentation before you rely on any platform detail.

Juridiske merknader er på engelsk, og den engelske versjonen gjelder.