Rate limiting in the cloud and mobile applications

Table of contents

• When you hit a limit
  • In grid view
  • What you can do
• Current usage limits popup
• The API page
  • Summary
  • General
  • API
• Reading a usage bar
  • Time windows
  • Types of usage

Every site in the zencontrol Cloud has limits on how much it can ask the cloud to do in a given period of time — how many pages and readings it fetches, how many lighting commands it sends, and so on. The limits keep one busy site from slowing down everyone else.

Most of the time you will never notice them. When a limit is reached, the portal tells you, keeps retrying in the background, and carries on as soon as the limit resets.

When you hit a limit

A red bar appears along the bottom of the screen:

A usage limit has been exceeded. Retrying until it resets, or you can refresh the page. View current limits

Nothing is broken and nothing is lost. The page keeps trying in the background, and the bar disappears on its own the moment requests start succeeding again — usually within a minute. You can also refresh the page.

The bar appears on plan view, dashboards, power, issues, alerts and emergency reports.

What you can do

• Wait. Limits reset on their own, usually every minute.
• Close extra tabs. Several grid views or dashboards open at once all count towards the same site limit.
• Check who or what is using the most on the API page (below), then decide whether that usage is expected.
• If you regularly hit limits during normal work, contact zencontrol about a higher allowance.

Current usage limits popup

Clicking View current limits on either warning opens a popup listing everything that is at a limit right now.

Each card is a site or tenancy, and under it are the types of usage that have run out, with a bar showing how full each one is (always 100% here, since these are the ones at their limit). Where the usage can be attributed to individual people, clicking a row expands it to show who.

Only general cloud usage appears here. Third-party API limits are not included.

If you open the popup after a limit has already cleared you will see “Nothing is usage limited” — that is good news, it means everything is back to normal. The alert will disappear when the rate limit has been lifted.

The API page

For the full picture, open API in the site menu. It shows current usage for everything, not just what is at a limit, so you can see what is running hot before it becomes a problem.

If you do not see this link in the sidebar, you may not have the required feature visibility and will need to contact someone with elevated privileges to grant you this feature.

The page has up to three tabs, depending on what your site has enabled, plus a Refresh button that re-reads the current figures. (Refresh pauses for a few seconds after each use.)

Summary

The landing tab: the ten highest usages across the site, and the ten users with the highest usage.

• Highest usage — the area and type of usage, which time window it covers, and how full it is.
• Highest usage by user — the same, broken down by person, so you can see who is generating the most traffic.

Clicking any of the rows jumps straight to that area and type on the General or API tab.

General

Everything the portal, the mobile apps and your users are doing.

Each card is an area (the site itself, or one of its tenancies). Within a card, usage is grouped by type, with a bar per time window.

At the top you can:

• Area — show only certain sites or tenancies.
• Type — show only certain kinds of usage.
• Sort by — order the cards by overall usage, or by a particular time window, so the busiest appears first.
• Clear filters — reset everything back to the default view.

Your filters are kept in the page address, so a filtered view can be bookmarked or shared.

API

The same layout, for traffic coming from third-party integrations using the zencontrol API. This tab shows actual request counts (for example “420 of 600”) rather than percentages, since API users generally want the exact numbers.

Reading a usage bar

• The label on the left says which time window the bar covers.
• Resets in … underneath counts down to when that window starts again.
• The bar fills as usage climbs, and changes colour as it gets close to the limit: teal up to 70%, orange from 70%, red from 90%.
• The value on the right is a percentage on the General tab, or a count on the API tab.
• If a bar can be broken down by user, an arrow appears at the end of the row. Click anywhere on the row to expand it and see each person’s share.

Time windows

Types of usage

You will only see the types that apply to your site.