credentials.fetch() returns an HTTP response for both successful and failed app calls. It does not convert a Salesforce error response into StateMachinesError, and it never retries a request.
Check the status and response body before assuming the request reached a native app operation. Network failures can reject without a response.
Identify State Machines errors
The app URL can return a State Machines error before the app handles the request. These errors use a JSONerror object.
An instruction to retry after a delay does not prove an ambiguous native write had no effect. Reconcile the app state before repeating a write.
Inspect native app errors
Salesforce REST and Bulk errors use their native error arrays. SOAP failures use SOAP faults. OAuth failures use the OAuth error shape. Read the error code for that protocol, rather than parsing every body as a State Machines management error. For field and object failures, inspect the target API version’s describe response. For permission failures, verify the actor. For an unsupported operation, check known differences.Compare recorded requests
Usesm.requests.list({ environmentId }) to inspect recorded calls, newest first. If a call is missing, confirm the environment and app name, clear status and method filters, and include the call’s timestamp in the time range. Start a new first page after changing filters.
Check respondedBy on a matching record. gateway means the gateway produced the error response. The app may still have run the request. The gateway can fail after it forwards the request. Refusals from the app runner, such as capacity_exceeded and unsupported_protocol, are recorded with respondedBy: 'app' and a null errorCode.
sm.requests.get(id) adds selected headers and body previews. For a missing body, inspect coverage, reason, and encoding before downloading it. omitted means no body was stored. A body download then returns not_found. A binary body has no text preview. previewTruncated means only the start of a stored text body appears in the detail response.
sm.requests.body(id, 'request') or 'response' returns the stored bytes, including any redactions. XML, multipart, and credential-route bodies can be omitted even when the request itself succeeded.
sm.requests.stats({ environmentId, from, to }) summarizes recorded calls over a time range. Pass from and to as SDK Date values. Search requires both ends of the window too. The window can be at most 7 days. Recording is best effort, so missing entries or aggregate counts cannot establish that no request occurred.
Capture the environment ID, app version, method, path, response status, and sanitized error when reporting a problem. Exclude credentials and sensitive body data.
See requests and audit events for filters, coverage fields, and statistics. For lifecycle changes rather than app responses, inspect the environment’s audit events.