Agentforce
Agentforce action errors: safe failures and retries
Handle Agentforce action failures with explicit outcomes, safe messages and retry rules. Includes a failure-test worksheet and Apex limit caveats.
A timed-out refund request may already have reached the payment provider. Retrying it immediately can create a second refund.
Design your Agentforce action around the business outcome you can prove. Separate confirmed success, a rejected request and an unknown outcome. A friendly message or a success field helps the agent interpret a result; neither guarantees that its next response will be correct.
Salesforce’s Apex action guidance recommends clear input and output descriptions, graceful error handling and user-friendly messages. It also distinguishes instruction-based sequencing from deterministic logic. Put essential checks in the action or workflow itself.
Return the state you can establish
The following is a proposed application contract, not a set of built-in Agentforce status values. Adapt it to the operation and expose only information the caller may receive.
| Outcome | Evidence required | Next step |
|---|---|---|
COMPLETED | The system of record confirms the intended change | Return the permitted result and reference |
REJECTED | A business rule or authorization check rejected the request | Explain the allowed next step without exposing private details |
PENDING | An asynchronous operation was accepted | Return a tracking reference; do not claim completion |
UNKNOWN | The request may have reached the destination, but its final state is unconfirmed | Reconcile using the operation reference before retrying |
FAILED | The operation is known not to have completed | Route to a supported recovery path |
For a payment, use the payment system’s result as the evidence. Successfully inserting a Salesforce request record proves only that the request was recorded. For asynchronous work, make the eventual outcome visible through a status check or an operational queue.
Keep a safe customer message separate from diagnostic detail. A raw exception can contain record identifiers, field values or internal configuration. Log what your support team needs under appropriate access controls; return only the explanation the customer is allowed to see.
Handle recoverable errors without hiding partial work
Catch exceptions that your action can meaningfully handle. If a bulk operation allows partial success, inspect each result and preserve the mapping to its input. Decide whether the business operation permits partial completion before choosing that behavior.
A catch block does not automatically undo earlier successful work. Define transaction boundaries and rollback behavior deliberately. An external API call can also create a change outside the Salesforce transaction, so a Salesforce rollback alone does not prove that the external change was reversed.
Some failures cannot be converted into your preferred response. Salesforce documents uncatchable exceptions, including System.LimitException. A broad catch (Exception e) is therefore not a guarantee that the action returns normally. Avoid unnecessary queries and writes, and test the surrounding fallback when the action cannot return its contract.
Reconcile before retrying a write
Give each business operation a durable identifier that survives retries. Where supported, pass an idempotency key to the external service and store enough information to retrieve the original outcome. A check followed by an unprotected insert is vulnerable to concurrent requests; uniqueness needs enforcement at the system that performs the write.
Set a bounded retry policy for the failures the operation can safely retry. Do not keep retrying a permission denial or an unchanged business rejection. For a timeout with an unknown outcome, check the destination’s recorded state first.
Agentforce also has platform-level service errors. Preserve the trace reference for support. A platform error and a business rejection should not be collapsed into the same customer explanation.
Test the spoken answer and the actual record
Run the same request through a success, a denial, a timeout and a repeated submission. For every run, compare the agent’s answer with the destination record or operation log. Include a request that presses the agent to claim success despite a failed action.
The pilot evaluation worksheet includes outcome, permission and duplicate-write cases. Fill it with observed results from your environment. This guide describes a design and test method; it does not report a completed sandbox or production test.
Release the write action only when its owner can explain what happens after an ambiguous result. That recovery path matters as much as the normal response.