Limits and Quotas

To prevent abuse, avoid slowdowns, and ensure that all users make responsible use of our APIs, we enforce quota limits. If you perform too many requests you may exceed your quota; in this case, you will receive an error as a response until when your quota will be restored.

We enforce two different kinds of limits, based on the time range that they apply to.

📆  Long-term usage limits

Long-term usage limits are meant to avoid improper usage of the APIs, by setting a limit on the maximum amount of requests in a certain period.

Long-term Usage quotas are different based on the app visibility!

If the app is public every user that has access to a specific company through a specific app shares (and consumes) the same quotas as other users that have access to the same company through the same app, if the app is private the quotas are no more related to the app but only to the company, this means that creating a new private app won't increase your quotas.

The quota limits are the following:

API limit type	Limit
Requests per hour	1.000 requests per hour on a company-app couple
Requests per month	40.000 requests per month on a company-app couple for public apps
Requests per month	40.000 requests per month per company for private apps

Long-term limits use fixed time windows: these quotas are reset at the beginning of a new hour or month.

If the limit is exceeded, the API returns a 403 Forbidden HTTP status code; the response also includes a Retry-After header, indicating how long you should wait before retrying the request (in seconds).

⏱  Short-term rate limits

Short-term rate limits are meant to avoid usage spikes that could affect the system availability, by preventing applications from sending too many requests in a short-time interval.

Short-term Usage quotas are company-related!!!

This means that every app and user that has access to a specific company shares (and consumes) the same quotas with other apps and users that have access to the same company.

The quota limit is the following:

API limit type	Limit
Requests every 5 minutes	300 requests every 5 minutes

Short-term usage limits use a sliding-window algorithm, check the additional resources for further info.

If the limit is exceeded, the API returns a 429 Too Many Requests HTTP status code. The response also includes a Retry-After header, indicating how long you should wait before the request (in seconds).

📑  HTTP Headers and response codes

Every response contains several HTTP headers containing info about long-term usage limits.

Header	Description
RateLimit-HourlyRemaining	The number of requests remaining for the current hour.
RateLimit-HourlyLimit	The maximum number of requests you are permitted to make per hour.
RateLimit-MonthlyRemaining	The number of requests remaining for the current month.
RateLimit-MonthlyLimit	The maximum number of requests you are permitted to make per month.

Here you can find an example of the HTTP response:

HTTP/1.1 200 OK
Date: Tue, 05 May 2020 17:27:06 GMT
Status: 200 OK
RateLimit-HourlyRemaining: 840
RateLimit-HourlyLimit: 1000
RateLimit-MonthlyRemaining: 1430
RateLimit-MonthlyLimit: 20000

🌊  Is it still not enough?

We designed our quotas to be able to satisfy the needs of the majority of the use cases. Nevertheless, in some cases, the default quotas could prove to be scarce, and in this situation, the only way is to increment the quota limit.

If you think that your use case requires a higher quota, you can try to request us additional quota. It isn't automatic though, you'll have to explain your use case in detail to our team and demonstrate why our quotas are not sufficient to resolve it.

We can increment only the long-term usage limits.

Short-term rate quotas can't be incremented!

If you're facing an issue with short-term rate quota, e.g. you're obtaining a 429 Too Many Requests error response, it means that you're not managing our APIs correctly. If that's the case, we'll reject every additional quota request we'll receive, and you should instead read the next section.

💆‍♂️  Keep calm and deal with quotas!

As explained above, if the rate limit will be exceeded you'll receive a 429 response to your requests. This is not a fatal error and we expect you to retry the request after a short interval; if the requests will keep arriving too quickly, your requests will result in another error result, and so on.

It is then important to gradually increase the delay between requests to overcome this issue, this is usually done by applying exponential back-off to your requests.

Here you can find some code examples that you can use to introduce exponential back-off on your code:

C#

// We apply exponential backoff to our C# SDK
// https://github.com/fattureincloud/fattureincloud-csharp-sdk/

// We suppose to use the http://www.thepollyproject.org
// and the https://github.com/Polly-Contrib/Polly.Contrib.WaitAndRetry libraries
// to implement the exponential back-off
// to install them using the .Net cli:
// dotnet add package Polly
// dotnet add package Polly.Contrib.WaitAndRetry

using System;
using Polly;
using It.FattureInCloud.Sdk.Api;
using It.FattureInCloud.Sdk.Model;
using It.FattureInCloud.Sdk.Client;
using Polly.Contrib.WaitAndRetry;

namespace Backoff
{
    class Program
    {
        static void Main(string[] args)
        {
            Configuration config = new Configuration();
            config.AccessToken = "YOUR_ACCESS_TOKEN";

            var apiInstance = new ProductsApi(config);
            var companyId = 11;

            var maxRetryAttempts = 5;
            var pauseBetweenFailures = Backoff.ExponentialBackoff(TimeSpan.FromSeconds(2), retryCount: maxRetryAttempts);

            var retryPolicy = Policy
                .Handle<ApiException>()
                .WaitAndRetry(pauseBetweenFailures);

            retryPolicy.Execute(() =>
            {
                ListProductsResponse result = apiInstance.ListProducts(companyId);
                Console.Write("\n successful");
                Console.Write(result);
            });
        }
    }
}

Go

// We apply exponential backoff to our Go SDK
// https://github.com/fattureincloud/fattureincloud-go-sdk/

// We suppose to use the https://pkg.go.dev/github.com/cenkalti/backoff/v4 library
// to implement the exponential back-off
// to install it:
// go get github.com/cenkalti/backoff/v4

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	backoff "github.com/cenkalti/backoff/v4"
	fattureincloudapi "github.com/fattureincloud/fattureincloud-go-sdk/v2/api"
)

var (
	companyId     = int32(2)
	auth          = context.WithValue(context.Background(), fattureincloudapi.ContextAccessToken, "YOUR_ACCESS_TOKEN")
	configuration = fattureincloudapi.NewConfiguration()
	apiClient     = fattureincloudapi.NewAPIClient(configuration)
)

func main() {
	operation := func() error {
		resp, _, err := apiClient.ProductsAPI.ListProducts(auth, companyId).Execute()
		if resp != nil {
			json.NewEncoder(os.Stdout).Encode(resp)
		} else {
			fmt.Println(err)
		}
		return err
	}
	err := backoff.Retry(operation, backoff.NewExponentialBackOff())
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error %v\n", err)
		return
	}
}

Java

// We apply exponential backoff to our Java SDK
// https://github.com/fattureincloud/fattureincloud-java-sdk/

// We suppose to use the https://resilience4j.readme.io library to implement the exponential back-off
// to install it see: https://search.maven.org/artifact/io.github.resilience4j/resilience4j-retry/1.7.1/jar

import io.github.resilience4j.core.IntervalFunction;
import io.github.resilience4j.retry.Retry;
import io.github.resilience4j.retry.RetryConfig;
import io.github.resilience4j.retry.RetryRegistry;
import io.vavr.CheckedFunction0;
import it.fattureincloud.sdk.ApiClient;
import it.fattureincloud.sdk.ApiException;
import it.fattureincloud.sdk.Configuration;
import it.fattureincloud.sdk.api.ProductsApi;
import it.fattureincloud.sdk.auth.OAuth;
import it.fattureincloud.sdk.model.ListProductsResponse;

public class Application {

    public static void main(String[] args) throws Throwable {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        defaultClient.setBasePath("https://api-v2.fattureincloud.it");

        OAuth OAuth2AuthenticationCodeFlow = (OAuth) defaultClient.getAuthentication("OAuth2AuthenticationCodeFlow");
        OAuth2AuthenticationCodeFlow.setAccessToken("a/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZWYiOiJoMWJVQWJiVmpDT3ZqWmliYXlhOGMzcEQ2aEVEeENPcSIsImV4cCI6MTY0MjA4NDgzNH0.mBOAhimqtRV6WurlfVWNj9Sq7zOBZvGqSzV1swG0AN4");

        RetryConfig config = RetryConfig.custom()
                .maxAttempts(10)
                .retryExceptions(ApiException.class)
                .intervalFunction(IntervalFunction.ofExponentialBackoff(1000, 2))
                .build();

        RetryRegistry registry = RetryRegistry.of(config);
        Retry retry = registry.retry("listProducts", config);

        Retry.EventPublisher publisher = retry.getEventPublisher();
        publisher.onRetry(event -> System.out.println(event.toString()));

        ProductsApi apiInstance = new ProductsApi(defaultClient);

        CheckedFunction0<ListProductsResponse> retryingListSuppliers =
           Retry.decorateCheckedSupplier(retry,
               () -> apiInstance.listProducts(2, null, null, null, null, null));

        System.out.println(retryingListSuppliers.apply().getData());
    }
}

JavaScript

// We apply exponential backoff to our JavaScript SDK
// https://github.com/fattureincloud/fattureincloud-js-sdk/

let defaultClient = fattureInCloudSdk.ApiClient.instance;
let OAuth2AuthenticationCodeFlow =
  defaultClient.authentications["OAuth2AuthenticationCodeFlow"];
OAuth2AuthenticationCodeFlow.accessToken = "YOUR_ACCESS_TOKEN";

let productsApiInstance = new fattureInCloudSdk.ProductsApi();

var companyId = 16;
var opts = {};

const delay = (retryCount) =>
  new Promise((resolve) => setTimeout(resolve, 2 ** retryCount * 1000));
const getProd = async (retryCount = 0, lastError = null) => {
  if (retryCount > 20) throw new Error(lastError);
  try {
    return await productsApiInstance.listProducts(companyId, opts);
  } catch (e) {
    await delay(retryCount);
    return getProd(retryCount + 1, e);
  }
};

console.log(await getProd());

PHP

// We apply exponential backoff to our PHP SDK
// https://github.com/fattureincloud/fattureincloud-php-sdk/

// We suppose to use the https://github.com/stechstudio/backoff library
// to implement the exponential back-off
// to install: composer require stechstudio/backoff

$backoff = new Backoff(10, 'exponential', 10000, true);

$accessToken = "YOUR_ACCESS_TOKEN";
$config = Configuration::getDefaultConfiguration()->setAccessToken($accessToken);
$service = new UserApi(new Client(), $config);

$result = $backoff->run(function() {
  return $this->service->listUserCompanies();
});
return $result; // it contains the result of the closure

Python

# We apply exponential backoff to our Python SDK
# https://github.com/fattureincloud/fattureincloud-python-sdk/

# We suppose to use the https://github.com/litl/backoff library to implement the exponential back-off
# to install: pip install backoff

import fattureincloud_python_sdk
from fattureincloud_python_sdk.api import products_api
from fattureincloud_python_sdk.exceptions import ApiException
import backoff
import collections
collections.Callable = collections.abc.Callable # needed if you are using python > 3.10

@backoff.on_exception(backoff.expo, ApiException, max_tries=10)
def get_products(configuration, company_id):
        with fattureincloud_python_sdk.ApiClient(configuration) as api_client:
            products_api_instance = products_api.ProductsApi(api_client)
            products_api_instance.list_products(company_id)
        return


configuration = fattureincloud_python_sdk.Configuration()
configuration.access_token = "YOUR_ACCESS_TOKEN"
configuration.retries = 0 # needed to implement custom backoff

company_id = 11
get_products(configuration, company_id)

Ruby

# We apply exponential backoff to our Ruby SDK
# https://github.com/fattureincloud/fattureincloud-ruby-sdk/
require 'fattureincloud_ruby_sdk'

FattureInCloud_Ruby_Sdk.configure do |config|
# Configure OAuth2 access token for authorization: OAuth2AuthenticationCodeFlow
config.access_token = "YOUR_TOKEN"
end
suppliers_api_instance = FattureInCloud_Ruby_Sdk::SuppliersApi.new

retries = 0
max_retries = 20
company_id = 2

begin
    company_suppliers = suppliers_api_instance.list_suppliers(company_id)
    puts company_suppliers
rescue FattureInCloud_Ruby_Sdk::ApiError => e
  if retries <= max_retries
    retries += 1
    sleep 2 ** retries
    retry
  else
    raise "Giving up on the server after #{retries} retries. Got error: #{e.message}"
  end
end

TypeScript

// We apply exponential backoff to our TypeScript SDK
// https://github.com/fattureincloud/fattureincloud-ts-sdk/

import {
  Configuration,
  ProductsApi,
} from "@fattureincloud/fattureincloud-ts-sdk";

const apiConfig = new Configuration({
  accessToken: "YOUR_ACCESS_TOKEN",
});

let productsApiInstance = new ProductsApi(apiConfig);

var companyId = 2;
var opts = {};

const delay = (retryCount: number) =>
  new Promise((resolve) => setTimeout(resolve, 2 ** retryCount * 1000));
const getProd: any = async (retryCount = 0, lastError?: string) => {
  if (retryCount > 20) throw new Error(lastError);
  try {
    return await productsApiInstance.listProducts(companyId);
  } catch (e: any) {
    await delay(retryCount);
    return getProd(++retryCount, e.message);
  }
};

console.log(await getProd());

Alternatively, you can use the Retry-After header to wait the right amount of time before sending your request again.

📚  Additional Resources

• Rate limiting using the Fixed Window algorithm
• Rate limiting using the Sliding Window algorithm
• Exponential Backoff
• Exponential Backoff And Jitter
• Better Retries with Exponential Backoff and Jitter for Java
• Retry-After Header
• 403 Forbidden
• 429 Too Many Requests
• Windowing examples in the Apache Beam documentation
• Retry with resilience4j