REST API

Rate Limits

To maintain consistent availability of the API service, limits are applied to API usage based on: 

  • Frequency. The number of requests processed over a particular time period.
  • Concurrency. The number of requests processed at the same time.

Counts can be per user, per project, per account, or a combination of these, depending on the endpoint.

When a rate limit is hit, the API service returns a 429 status code in the HTTP response. The response body contains additional details of the limit encountered as illustrated below:

{
    "response": {
        "code":"MAX_OPERATIONS_LIMIT_EXCEEDED",
        "errors":[
            { 
                "key": "too.many.requests",
                "message": "The limit of 10 concurrent Smartling file API operations for this project has been exceeded.",
                "details": {
                    "errorId":"xpvrz3zc"
                }
            }
        ]
    }
}

You should explicitly check for 429 status codes and handle them appropriately.

Handling rate limiting in client applications

The general approach to handling rate limiting is to retry the request after a delay. The best practice for this is to gradually increase the delay exponentially, with some randomness, after each failed attempt, up to some maximum delay. In addition, it's recommended to abandon the retry effort after some maximum number of attempts. 

Below is an example code snippet in Python illustrating how this might be done:

for attempt in range(max_retries):
    # get access code inside loop in case it expires during retries
    headers = {'Authorization': 'Bearer ' + authenticator.get_access_token()}
    # send api request
    r = requests.get('https://api.smartling.com/files-api/v2/projects/' + project_id + '/file/status',
                      headers=headers,
                      params=params)

    # if we're not rate limited, then no need for any retries
    if r.status_code != 429:
        break

    randomized_exponential_delay = (2 ** attempt) + random.random()
    time_to_sleep = min(randomized_exponential_delay, max_delay)
    time.sleep(time_to_sleep)

# continue processing response, potentially handling other error types

A typical value for the maximum delay is 30-60 seconds; and for the maximum number of retries, 5-10.

A similar retry approach to the above could be used for certain other types of errors, such as intermittent network or server errors. See Error Handling for details.

Was this article helpful?