API rate limits

Helcim's API rate limits are implemented to ensure the stability and security of our services. They help to prevent abuse and overloading of our system by controlling the number of requests a merchant can make to our API within a certain time period. Without these limits, bad actors could overwhelm our system with excessive requests, leading to degraded performance, service downtime, or security vulnerabilities (e.g., denial-of-service attacks).

By managing the frequency of requests, these rate limits help maintain the availability and integrity of our service for all merchants and these limits should be factored into your integration with the Helcim API.

Our API rate limits are enforced by tracking the number of requests a merchant makes to our API in a given time window. These limits are enforced per Helcim merchant account and will aggregate requests from different API Access Configurations on the same account and count them towards the following limits.

• Concurrent Limit: 5 calls in progress at one time.
• Minute Limit: 100 calls per minute.
• Hourly Limit: 3000 calls per hour.

When a merchant exceeds these limits, our system will block further requests until the limit resets, preventing overload. This process is automated through the use of HTTP headers, which tell merchants how many requests are left in the current period.

minute-limit-remaining: 99
hour-limit-remaining: 2999

If a merchant exceeds the limit, they will receive an HTTP status code of 429 ("Too Many Requests") as a response from the Helcim API, signaling that you need to wait before sending more requests.

Rate limit management

The best defence against hitting the API rate limit involves tracking the API rate limit headers to ensure that your integration can adapt and spread requests out if possible. If you do hit the rate limit, then you will need to wait until your rate limit has reset before you can successfully send new requests.

Helcim uses a sliding window algorithm to track and limit requests and slides forward every second. This is done by dividing time into series of overlapping intervals and counting requests made within each per minute and per hour interval. Requests are counted within each window and if the number of requests exceeds the limits mentioned above, then subsequent requests are rejected until old requests are discarded to allow new ones to be received.