New feature: Rate limit information headers will be included in HTTP responses

New feature: Rate limit information headers

In the coming days, rate limit information that was only available from the check daily API usage endpoint will be added to responses from any requests authenticated using an API key. This update is currently enabled for our most frequently used APIs (Contacts, Deals, Email, Companies, and Engagements), and is in the process of being rolled out to the rest of our APIs.

What's happening?

The main way for API consumers to check the daily rate is to use the check daily API usage endpoint, and while this is adequate this presents a few drawbacks that needed to be addressed. We are now providing an additional way developers receive this information. The change being introduced is to make it easier for your integration to monitor the rate limits, and to provide this information without the need for an outgoing request.

What's changed?

Starting immediately, API requests authenticated with a HubSpot API key will include four new headers in the HTTP response. These headers reflect the per day and per second rate limits and the remaining requests still allowed for the API key that was used for the request:

• X-HubSpot-RateLimit-Daily - The number of API requests that are allowed per day.
• X-HubSpot-RateLimit-Daily-Remaining - The number of API requests still allowed for the current day. The current day is calculated as midnight to midnight based on the time zone setting of the account, which can be obtained from the account details endpoint.
• X-HubSpot-RateLimit-Secondly - The number of API requests that are allowed per second.
• X-HubSpot-RateLimit-Secondly-Remaining - The number of API requests still allowed for the current second.

This does not affect the existing functionality or response data of any of our APIs, but adds new functionality and makes checking rate limits more convenient. An important note however, in the case of failure to gather rate limit information, the rate limit headers will not be present in the outgoing response.

For more details about working with HubSpot's API rate limits, please see this page:
https://developers.hubspot.com/docs/faq/working-within-the-hubspot-api-rate-limits

What systems are affected?

This is currently live for the Contacts, Deals, Email, Companies, and Engagements APIs, and will soon be rolled out to all APIs.

Please note: This update only affects requests that are authenticated using a HubSpot API key. Support for requests authenticated using an OAuth access token is coming soon.

Please let us know if you have any questions by replying to the forum post.