Allegion Developer Portal

Rate Limiting for BLE Credential APIs

Rate Limiting for BLE Credential APIs

Effective Date: 12.02.2024

Last modified: 11.21.2024

Introduction

The BLE Credentialing APIs are essential for developers and Access Control Systems, facilitating numerous requests daily. To ensure reliability and scalability, we implement rate limits on these APIs. These limits prevent bursts of traffic, maintaining API stability. Exceeding the limit results in a 429-status code error.

What is Rate Limiting?

Rate limiting controls the frequency of API requests by setting a maximum number of requests allowed within a specific timeframe, such as per minute or per second. For instance, you might be allowed 100 requests per minute. Exceeding this limit triggers an error message instructing you to slow down.

Rate Limiting Policies

Our APIs use a fixed time interval rate limiting approach. A set number of requests is allowed within a predefined interval. Once the limit is reached, further requests are denied until the interval resets.

Example:

Consider the "Get All Credentials" API with a limit of 100 requests per 60 seconds:

  • T = 60 seconds.
  • Requests 1-100 made between T = 0 and T = 55 seconds.
  • Subsequent requests made from T= 56 to T= 60 seconds will be rejected with a 429 error.
  • At T= 60 seconds, the limit resets, allowing another 100 requests for the next interval.

Rate Limits Table

API Name Rate Limit Time Frame Description
Authentication Token The rate limiting for the Authentication Token API is determined and enforced by our identity provider.
Create Credential 100 requests 60 seconds Permits up to 100 requests per minute.
Create Raw Credential 100 requests 60 seconds Allows for up to 100 requests per minute.
Save No-Tour Payloads 100 requests 60 seconds Up to 100 requests can be made per minute.
Get Credential by Credential Id 100 requests 60 seconds Allows up to 100 requests per minute.
Get Credential by User Id 100 requests 60 seconds Permits up to 100 requests per minute.
Get All Credentials 100 requests 60 seconds Allows up to 100 requests per minute.
Delete No-Tour Payload by Device Serial Number 100 requests 60 seconds Permits up to 100 requests per minute.
Delete No-Tour Payloads by Credential Id 100 requests 60 seconds Allows up to 100 per minute.
Delete Credential by Credential Id 100 requests 60 seconds Permits up to 100 requests per minute.
Delete Credential by User Id 100 requests 60 seconds Allows up to 100 requests per minute.

HTTP Headers and Response Codes

Use HTTP response headers to monitor rate limits:

  • x-rate-limit: Maximum requests allowed for the endpoint.
  • x-rate-limit-remaining: Remaining requests for the current window.
  • x-retry-after: Seconds to wait before retrying.
  • x-rate-limit-reset: Time until the rate limit resets, in UTC Epoch seconds.

A 429 "Too Many Requests" response indicates the rate limit has been exceeded. The response body will include an error message and retry instructions.

Example: Get All Credentials Endpoint

Request: GET https://developerapi.allegion.com/SMC/credentials/mobile

Response Headers Before Limit Exceeded:

HTTP/1.1 200 OK
Content-Type: application/json
x-rate-limit: 100
x-rate-limit-remaining: 99

Response Headers After Limit Exceeded:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
x-rate-limit: 100
x-rate-limit-remaining: 0
x-retry-after: 30
x-rate-limit-reset: 2024-10-10T08:57:58.1747411Z

Response Body:

{
    "error": "You have exceeded the maximum number of requests allowed for this API. Please wait for 30 seconds before trying again."
}

Recovering from a Rate Limit

When you hit a rate limit, the API returns a 429 "Too Many Requests" error. This indicates that you've exceeded the allowed number of requests for the current time window. Here's how you can handle this situation effectively:

  • When a 429 error occurs, check the x-rate-limit-reset header to determine when the rate limit will reset. This header provides the time in UTC epoch seconds, allowing you to calculate when to resume requests.
  • Use an exponential backoff strategy to manage retries. Start with a short wait time (e.g., a few seconds), and double the wait time after each failed attempt. This approach helps reduce the load on the server and increases the likelihood of a successful request once the limit resets.
  • Design your client application to be aware of existing rate limits. Pause requests until the current window expires, especially if you consistently hit the limit.

Tips to Avoid Being Rate Limited

  • Avoid sending large bursts of requests. Instead, spread them out over time. This can be achieved by implementing a throttling mechanism that controls the rate of requests.
  • Keep track of your request rates and adjust them dynamically based on the current load and rate limit status. This proactive approach helps prevent reaching the limit unexpectedly.
  • If you anticipate a significant increase in traffic (e.g., during a product launch or promotion), contact Allegion support in advance to discuss potential rate limit adjustments.
  • Make only necessary requests. Review your application's logic to ensure that each API call is essential and avoid redundant requests.

FAQs

Is there an endpoint that returns all endpoints for a resource, including the different rate limits and times to retry?

No, we do not provide a dedicated rate-limit endpoint. However, you can use the following response headers to monitor your account's rate limit and the number of requests remaining for the current minute: x-rate-limit and x-rate-limit-remaining.

What happens when the rate limit is reached?

When the rate limit is reached, the API does not process the request and returns a 429-response code. The x-retry-after header specifies the time in seconds you must wait before retrying.

Will batching calls reduce the number of API calls? How about making parallel calls?

No, batching calls will not reduce the number of API calls, nor will making parallel calls. Each API request counts towards the rate limit.

What should I do if I hit the rate limit?

If you hit the rate limit, wait until the rate limit resets. Check the x-retry-after header to determine how long you need to wait before making another request. Implementing exponential backoff can help manage retries effectively.

How can I request a higher rate limit?

To request a higher rate limit, contact our support team at developer.support@allegion.com. Provide details about your use case and expected request volume, and we will evaluate your request.

What happens if I consistently exceed the rate limit?

Consistently exceeding the rate limit may result in temporary or permanent suspension of your access to the API. Please adhere to the rate limits to avoid any disruptions. If you need a higher rate limit, consider contacting our support team for assistance.