Custom Quotas

Adding custom quotas

Some APIs have pricing models that are more complicated than a simple 'Request' limit. For example, here is an API where it is more expensive for the provider to upload an image. You'll notice that the "Uploads" item allows fewer calls and has a higher overage fee than the "Requests" item.

If your API falls into a more complicated category, consider adding custom quotas to your API. Here's what you need to know.

🚧

Custom quotas and clarity

The more custom quotas that you have, the more likely a developer may become confused about your API's usage. This can result in fewer subscriptions and/or more disputed overage fees. When you add a custom quota, be as explicit as possible as to what the item is, how it will be incremented and what the quota counts.

You can create up to four custom quotas. Some examples of types of custom quotas are Videos, Messages, Downloads, Items Returned, etc.

❗️

Restricted characters

Custom quota objects cannot include special characters like commas. On the RapidAPI Hub, you may see an error of 'Parse Error' if the billing header contains a special character.

Default quota behavior

By default, RapidAPI increments each quota by one unit on every request, with the exception of response code errors. If your API returns an error code equal to or greater than 500, RapidAPI won’t increment the usage for that user.

Incrementing quota by endpoint

By having quotas whose usage is increased only when specific endpoints are being requested, it is possible to associate endpoints and quotas. Every time the user requests that specific endpoint, the associated quota will be increased by one unit.

Incrementing quota by more than one increment

It is possible to override the default behavior and increment the quotas by a different number of units by sending a special header in the API response in the following format:

X-RapidAPI-Billing: [Quota]=[Value]

For example, to increment the Messages quota by 10 units, you would add the following header to the response:

X-RapidAPI-Billing: Messages=10

You can increment more than one quota as well by separating the values with a semicolon, like so:

X-RapidAPI-Billing: Messages=10; Images=3; Audio=2

Again, if you decide to increment a certain quota by more than one, we highly recommend including that information in the object's description on the pricing subscription page. Adding this information explicitly will make it easier for developers to understand your API's usage limits.