API Call Limit

How to teach your program to pause and resume.

Just a friendly reminder that the API call limit changed November 18th, 2013. It is now an average of 2 calls per second, with room for a burst of 40 calls at once.


The API call limit operates using a "leaky bucket" algorithm as a controller. This allows for infrequent bursts of calls, and allows your app to continue to make an unlimited amount of calls over time. The bucket size is 40 calls (which cannot be exceeded at any given time), with a "leak rate" of 2 calls per second that continually empties the bucket. If your app averages 2 calls per second, it will never trip a 429 error ("bucket overflow"). To learn more about the algorithm in general, click here.

Your API calls will be processed almost instantly if there is room in your "bucket". Unlike some integrations of the leaky bucket algorithm that aim to "smooth out" (slow down) operations, you can make quick bursts of API calls that exceed the leak rate. The bucket analogy is still a limit that we are tracking, but your processing speed for API calls is not directly limited to the leak rate of 2 calls per second.

Are you going over the API limit?

Before you submit a support ticket to ask our support team to raise your API limit, please take a moment to reflect upon what you’re about to do. Those limits exist for a reason. They’re not random rules that haravan came up with to make your life hard.

Automated tasks are great because you don't need to wait around while things get done. If an automated task takes 30 minutes to complete rather than 15, you won't feel the difference if you're doing something unrelated, fun, productive etc.

This article will show you how to tell your program to take small pauses to keep your app a few API calls shy of the API call limit and to guard you against a 429 - Too Many Requests error.

How to avoid the 429 error

Some things to remember:

  • You can check how many calls you've already made using the haravan header that was sent in repsonse to your API call:

    HTTP_X_haravan_SHOP_API_CALL_LIMIT (lists how many calls you've made for that particular shop)

X-haravan-Shop-Api-Call-Limit: 32/40

Keep in mind that X will decrease over time. If you see you're at 39/40 calls, and wait 10 seconds, you'll be down to 19/40 calls.

  • You can only get a maximum of 250 orders or products with one API call

  • You can only update one order or product with one API call

Let's use a real-world example (in this case, deleting products that are out of stock) to demonstrate how to make your program pause and resume.

In this article:

Creating your program

In your code editor of choice, create a new Ruby file. Call it, say, cleanup.rb.

Add to that blank file the code below. Then copy your API key, password and myharavan sub-domain in the relevant placeholders:

SHOPNAME = 'shopname'

CYCLE = 0.5 seconds     # You can average 2 calls per second

require 'rubygems'    # Need this to use the haravan_api gem.
require 'haravan_api' # Tellement utile to speak to your shop.

Below, add your engine. This one fetches all products and deletes the ones that are not available.

# Telling your shop who's boss.
url = "https://#{APIKEY}:#{PASSWORD}@#{SHOPNAME}.myharavan.com/admin"
haravanAPI::Base.site = url

# How many.
product_count = haravanAPI::Product.count
nb_pages      = (product_count / 250.0).ceil

# Do we actually have any work to do?
puts "Yo man. You don't have any product in your shop. duh!" if product_count.zero?

# Initializing.
start_time = Time.now

# While we still have products.
1.upto(nb_pages) do |page|
  unless page == 1
    stop_time = Time.now
    puts "Last batch processing started at #{start_time.strftime('%I:%M%p')}"
    puts "The time is now #{stop_time.strftime('%I:%M%p')}"
    processing_duration = stop_time - start_time
    puts "The processing lasted #{processing_duration.to_i} seconds."
    wait_time = (CYCLE - processing_duration).ceil
    puts "We have to wait #{wait_time} seconds then we will resume."
    sleep wait_time if wait_time > 0
    start_time = Time.now
  puts "Doing page #{page}/#{nb_pages}..."
  products = haravanAPI::Product.find( :all, :params => { :limit => 250, :page => page } )
  products.each do |product|
    puts product.title
    any_in_stock = product.variants.any? do |variant|
      variant.inventory_management == '' || variant.inventory_policy == 'continue' || variant.inventory_quantity > 0
    if not any_in_stock
      puts "--- Deleting #{product.title}..."

puts "Over and out."


If you remove all comments and puts, there aren't many lines of code left.

Running your program

Open a Ruby Console or launch your Terminal. Browse to your program and run it:

ruby cleanup.rb


This example would only happen in "edge cases" because unless the products in your shop are all out of stock you likely won't need to use a throttling mechanism in the way shown above to delete out of stock products. Nevertheless, there will be situations where it becomes critical to 'pause and resume' your program. Say you want to edit the price of all the products in your shop.

Code repository

The code above is available on github: https://github.com/carolineschnapp/delete-out-of-stock-products/blob/master/cleanup.rb