Scalability options
Bulk Operations
The Smartsheet API supports a number of bulk operations that can operate on multiple objects. Unlike single-object operations, bulk operations allow you to create, update, or delete multiple objects in a single request. For example, if you want to update 10 rows within a sheet, do so using a single Update Rows request, rather than executing 10 separate requests - one for each row.
Optional Bulk Operations
Several endpoints support optional bulk POST operations which exist alongside the standard single-object POST. For these endpoints, you may pass in either a single object or an array of objects. Depending on what was passed in, the Result object returned contains either a single object or an array. An example optional bulk operation is POST /favorites: you can pass in a single Favorite object to create a single favorite, or an array of Favorite objects to create multiple favorites in a single request. Endpoints which support bulk operations are noted as such in the API reference documentation.
NOTE: Most POST operations fail when attempting to create a single object which already exists (for example, favorites, shares, group members). However, for the corresponding bulk operations, these endpoints do not return an error if one or more items in the array already exist. Existing items are simply ignored, and the Result object returned omits them.
Partial Success
In general, the default behavior for bulk operations is to fail outright if any of the objects in the request are invalid for some reason. If successful, Smartsheet creates/updates/deletes all objects in the request; if not, no objects are changed.
However, there are some operations that support partial success, which means the operation still succeeds even if one or more of the objects in the request fails for some reason (for example, an object is invalid). Here is another example: if you want to update more than one row, you send more than one row object in your request. If a row object is invalid, that row update will fail, but the other row updates will succeed. Partial success is not the default mode for an operation and you must explicitly enable it by using a query string parameter. This is noted in the documentation for operations that support partial success.
When partial success is enabled, and one or more of the objects in the request fail to be added/updated/deleted, a standard Result object is returned, but with a message of 'PARTIAL_SUCCESS' (instead of 'SUCCESS'), and a resultCode of 3. Additionally, the object contains a failedItems attribute -- an array of BulkItemFailure objects that contains an item for each object in the request that failed to be added/updated/deleted.
Rate Limiting
Some operations, such as attaching a file and getting cell history, are resource intensive. To prevent abuse and undue stress on the Smartsheet servers, we reserve the right to enforce load limits on our systems. This is sometimes called rate limiting or throttling. The Smartsheet API's rate limits protect the system.
Important: Unless otherwise stated, an endpoint's rate limit is 300 requests per minute per API token.
Handle "Rate limit exceeded" Error
When API calls exceed an acceptable load, an HTTP 429 status will be returned along with the following response body:
{
"errorCode": 4003,
"message": "Rate limit exceeded."
}We recommend that you design your integration to gracefully handle this rate limit error. One way of doing that would be to have your integration sleep for a minimum of 60 seconds when this error is encountered, and then subsequently retry the request.
Alternatively, you might choose to implement exponential backoff (an error handling strategy whereby you periodically retry a failed request with progressively longer wait times between retries, until either the request succeeds or the certain number of retry attempts is reached). Note that the SDKs implement this behavior.
Avoid Executing "Rapid Fire" Updates
If the only thing your integration does is execute an Update Rows request once every second for the same sheet, that would only amount to a total of 60 requests per minute -- well within rate limiting guidelines. However, updating the same object in such rapid succession could result in save errors that negatively impact both your integration as well as user experience within the Smartsheet app. To avoid this scenario, design your integration such that API requests are never executed with rapid-fire succession against the same Smartsheet object. For maximum efficiency, consider batching up changes and submitting them in a single request using a bulk operation (for example, Update Rows or Add Columns.
Execute Requests Serially
Executing multiple API requests in parallel to update a specific Smartsheet object results in reduced performance and often results in errors due to save collisions. To avoid this scenario, design your integration such that API requests to update a specific Smartsheet object are always executed serially (that is, execute one request at time, not beginning the next request until the previous request has completed).
NOTE: Attempts to perform multiple concurrent updates to a sheet may result in error code 4004.
Use the Smartsheet SDKs
The SDKs provide default backoff and retry to accommodate rate limiting responses from the API. Note that the default maximum retry duration is typically 30 seconds. You may wish to increase this if your application is making many API calls in quick succession. For specific instructions per language, see the Readme for the respective SDK.