Rate limits

To help ensure that problematic applications and potential security threats don't impact other users of the system, we continue to employ methods of rate limiting for the v3 API.

Default limits have been increased to enable a greater number of requests per second and day per customer. By default Transactions Per Day and Transactions Per Second limits auto-scale based on the number of devices associated with your API key. You can review the headers of your requests to the API to determine the TPS/TPD rate at any time.

Rate limit headers

Before you reach the rate limit, the following headers are returned:

200 OK
...standard headers
X-RateLimit-TpdLimit: 10000
X-RateLimit-TpdRemaining: 6372
X-RateLimit-TpdReset: 86401
X-RateLimit-TpsLimit: 5
X-RateLimit-TpsRemaining: 2
X-RateLimit-TpsReset: 1.595

Header	Format	Notes
`X-RateLimit-TpdLimit`	Integer	The number of requests permitted before day rate limiting will be invoked. In the example above, the TPS is set to 10,000 requests per day (this limit is illustrative only).
`X-RateLimit-TpdRemaining`	Integer	The number of requests remaining in the next day before rate limiting will occur. In the example above, 6372 more requests can be made within the next day without triggering rate limits.
`X-RateLimit-TpdReset`	Integer	The number of seconds remaining before the TPD count (`TpdRemaining`) will be reset.
`X-RateLimit-TpsLimit`	Integer	The number of requests permitted before TPS rate limiting will be invoked. In the example above, the TPS is set to 5 requests per second (this limit is illustrative only).
`X-RateLimit-TpsRemaining`	Integer	The number of requests remaining in the next second before rate limiting will occur. In the example above, 2 more requests can be made within the next second without triggering rate limits.
`X-RateLimit-TpsReset`	Float	The number of seconds remaining before the TPS count (`TpsRemaining`) will be reset. NOTE: this is in seconds, but is a float (seconds.milliseconds) for greater accuracy.

Rate limit error

If you trigger rate limiting (i.e. make too many requests), the API will respond with a 429 HTTP status code, and the following response content.

429 Too Many Requests
...standard headers
X-RateLimit-TpdLimit: 10000
X-RateLimit-TpdRemaining: 6370
X-RateLimit-TpdReset: 86400
X-RateLimit-TpsLimit: 5
X-RateLimit-TpsRemaining: 0
X-RateLimit-TpsReset: 0.788
Retry-After: 1

{
    "code": "TOO_MANY_REQUESTS_TPS",
    "httpCode": 429,
    "message": "You have exceeded the request limit of 5 per 1 second for your API key. Please review the response headers for further details."
}

Note the additional Retry-After header that is returned.

Header	Format	Notes
`Retry-After`	Integer	The number of seconds before you retrying the request will succeed. Note that, unlike `TpsReset`, this is an integer (which matches the specification for `Retry-After`.)

The code will included which of the two limits you've exceeded. e.g. TOO_MANY_REQUESTS_TPS means the per second limit has been exceeded. TOO_MANY_REQUESTS_TPD means the per day limit has been exceeded. You can use this code or the headers to programatically respond to the limit (e.g. pausing in a loop and waiting before sending the next request).

The message content also provides a human-friendly indication of which of the two limits you've exceeded and what your rate limits are.

FAQs

What's the difference between TPD and TPS?

Transactions Per Day (TPD) is the total number of requests you can make to the API across a 24 hour period. It is reset at 12AM UTC each day.

Transactions Per Second (TPS) is the total number of requests you can make in a given second, and is reset every second.

How many concurrent requests can I make?

The number of concurrent requests you can make is influenced by a number of factors, and there's no hard and fast rule. It is important that if you are polling the API that you handle throttled responses as a part of standard operation.

However, you can use the TPS with an estimate of the average request response time to gauge the number of concurrent requests you might reasonably make without encountering throttling responses.

For example, if your TPS is 33, you can make 33 requests in a second. If the average response time for the request you're making is 100ms (as a nice, round example), you might reasonably expect 3 concurrent threads polling the API 10 times per second to operate without hitting against the TPS limit.

How are the auto-scaling limits determined?

For Transactions Per Day (TPD), the default is based on:

Number of devices x (1 x API call every 5 mins for Long Energy data + 1 x API call every 30 seconds for Short Energy data + 1 x API call every 5 mins for device status) + a buffer.

For Transactions Per Second (TPS) this is based on:

The number of devices divided by 3. So, for a fleet of 100 devices:

TPD = 100 devices x (288 + 2880 + 288) = 345,600 (+ buffer)
TPS = 100 devices/3 = 33

Please note that the default handling of auto-scaling may change in future, with any changes announced well in advance via communications channels such as our technical partners email list. Please check with your Wattwatchers account manager to ensure the appropriate members of your team are subscribed to this list.

How can I determine my TPS or TPD limit?

The limits are reflected in the X-RateLimit-Tpd-Limit and X-RateLimit-Tps-Limit headers of every request.

TPS and TPD limits are also included in error messages returned if you exceed these limits.

Can I increase my TPS/TPD limits?

We do offer customers the option to increase their TPS or TPD limits based on their use case and appropriate commercial arrangements. If you require increased limits, please contact your Wattwatchers account manager to discuss your options.

If my TPD limit is increased, when does it take effect?

Increases to TPD or TPS limits for an API key take effect immediately. The count against the limit is not reset until the next rollover point (i.e. if you have made 600 requests in a day at the time the TPD limit is increased, the 600 requests are still counted against the new, increased limit.)