Type to search...

Handling rate limitation with Shardimage PHP SDK

Rate limitation

Shardimage uses rate limitation to protect the API endpoints against unnecessary overloads. For the interruption free work, the developer needs to handle this limitation which is simple using the shardimage-php package. For more information about Shardimage rate limitation, please click here »

Handling rate limitation error has a simple conception. If request count exceeds the rate limit, in case of a single request, an exception will be thrown, if it’s multipart batch request, the result array will contain Response objects with the error.

The Response object contains an error class property which has the occurred error data, also the complete exception. It’s important to handle this exception in case of rate limitation because it stores the time limit when the rate limitation expires.


Short example with image upload. Let’s say, we have constantly running script, which uploading collected images. If we detect that the script reached the limitation, the script must wait before running again.

use shardimage\shardimagephp\auth\Client;
use shardimage\shardimagephpapi\web\exceptions\TooManyRequestsHttpException;
use shardimage\shardimagephpapi\api\Response;
$client = new Client([
    'apiKey' => '<apiKey>',
    'apiSecret' => '<apiSecret>',
    'imageSecret' => '<imageSecret>',
    'cloudId' => '<cloudId>',
$images = [
        // Collected images to upload
$client->defer(true);  // Turn on bulk upload
foreach ($images as $image) {
        'file' => $image,
            ], [
        'tags' => ['batch', 'examples', 'rateLimit'],
// Turning off the bulk upload will send the collected requests
$result = $client->defer(false);
$waitTime = null;
foreach ($result as $_result) {
    if ($_result instanceof Response) {
        // Error occured during upload
        $ex = $_result->error->exception;
        // Developer's duty to handle unsuccessful uploads,
        //  good practice to collect and put them into the next upload cycle
        if ($ex instanceof TooManyRequestsHttpException) {
            // Only setting waiting time, the response processing should be finished
            //  so we can decide which images should be reuploaded after the waiting
            $waitTime = $ex->getRateLimitReset();
        } else {
            // Handling and logging other errors.
    } elseif ($_result instanceof Image) {
        // Image created successfully
if (!is_null($waitTime)) {
    echo sprintf("Wait until: %s\n", date('Y-m-d H:i:s', time() + $waitTime));
Table of contents