In a previous blog post titled “Simplify Your API Code with New Composite Resources” we talked about the new composite resources in the Salesforce REST API. The composite resources provide a way to “batch” together several REST API calls in a single call, improving the performance of your app by reducing the number of round-trips to Salesforce, and simplifying your code.
However, now that you’re making several calls in a single composite resource call, what happens when one of those calls runs into a problem? How will your app gracefully handle the scenario where some operations in your composite call succeed and some operations fail? Fortunately, the composite resources have you covered.
Note that all composite resources return detailed information when any error occurs. It’s always a good idea to check the full response and make sure everything went according to plan.
High Level Parsing Errors
Since composite resources can have fairly complex request formats, Salesforce does some sanity-checks on the overall request body content before processing subrequests. If any error in the request body format is detected, Salesforce returns a 400 “Bad Request” error without processing any of the subrequests. An example where this could occur is in a composite resource call, if a subrequest is missing the required “referenceId” field this is treated as request error. The error response might look something like this:
If the request body is valid, Salesforce starts processing subrequests. Subrequests themselves could fail for a variety of reasons during processing, and each composite resource provides appropriate subrequest error information in the response data.
Errors in batch Resource Calls
If any subrequests result in errors in a batch resource call, the response will have a hasErrors field with a value of “true”. This field simply indicates that there were one or more errors in the list of subrequest calls. You’ll still need to examine the results array to determine which subrequests failed. Suppose you used the following request body in a batch resource call:
Notice the cleverly named “notARealResource” resource call, which we expect to fail. The response array would contain the results of the successful Account describe call, and the invalid “notARealResource” call:
By default, the batch resource processes all the subrequests in a batch, even if some of the subrequests fail. However, you can specify that Salesforce stop processing subrequests once a subrequest fails by using the haltOnError request field. If haltOnError is true, and a subrequest has an error, Salesforce won’t attempt to execute any subrequests that come after the subrequest that failed.
Here’s a simple example to help clarify this. Suppose we made a batch request with the following request body:
When we make a batch call with this request body, we get a response that has:
hasErrorsset to true, since there was one error.- An array of subrequest results which will be the results of a successful Account describe call, followed by a 404 “Not found” error result for the bad “notARealResource” call, followed by a 412 “Batch processing halted” error result indicating Salesforce stopped processing the batch and didn’t process the Contact describe call.
If we had set haltOnError to false, the results would be similar, but the response would contain the results of the successful Contact describe call instead of a 412 “Batch processing halted”.
Errors in tree Resource Calls
For the tree resource, if there’s any error when creating a record, none of the records in the request are created. The response will contain the hasErrors field set to true, and an array of records that failed, along with the reference ID you supplied for the record and detailed error information for the failure.
For example, suppose you made a tree resource call that included a SObject tree that looked like this:
The phone field is invalid, and causes an error when attempting to create the record. The response you get clarifies the source of the error:
Errors in composite Resource Calls
If a subrequest fails during processing with a composite resource call, the error is returned in the response in the results array. Suppose you used a request body that looked something like this:
In the response, you’d get an array of two items. The first item would have the results of creating a new Account record. The second item would contain a 400 error indicating “notARealResource” is, in fact, not a real resource:
Similar to the batch resource, the composite resource provides a way to control what happens if a subrequest fails. By default other subrequests are still processed, but by setting allOrNone to true in the request body, you can tell Salesforce to stop processing any subrequests once an error occurs and rollback any subrequests that completed before the error happened.
More Information
Hopefully you’ve now got a feel for how the composite resources handle errors, and how you can control what happens when a subrequest fails. Here’s a quick recap of the composite resources, suggested use cases, and subrequest error handling, in convenient table form:
| Resource | Use Case | Has Subrequest Error Flow Control? |
|---|---|---|
| batch | Combine unrelated subrequests into a single request. | Yes, using haltOnError |
| tree | Create a set of records, with parent-child relationships if needed, in a single request. | No. If the request fails, no records are created. |
| composite | Combine subrequests into a single request. Subrequests can have dependencies on other subrequests. | Yes, using allOrNone |
Feel free to check out the official docs, which include a series of more complex examples. For more information on the composite resources, see:
Examples and walkthroughs of using the composite resources in the REST API Developer Guide.
Reference documentation on the composite resources in the REST API Developer Guide.