📈 Rate Limiting

API rate limiting is a technique used to control the rate at which a user or an application makes API requests. It is used to prevent excessive usage of an API and ensure that the API remains available to all users. Govee's API rate limits are outlined below.

Rate Limits

Rate-limiting rules apply to all Govee Developer API accounts.

Rule	Rate Limit
Devices Per Day	10,000 / Day
List Devices Per Minute	10 / Minute
Get Device State Per Minute	10 / Minute Per Device
Control Device Per Minute	10 / Minute Per Device
Appliances Per Day	100 / Day
List Appliances Per Minute	10 / Minute
Control Appliance Per Minute	10 / Minute Per Device

Rate Limiting Headers

The returned HTTP headers show your current rate limit status:

Rate Limit Status	Description
*-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
*-RateLimit-Reset	The time the current rate limit window resets in UTC epoch seconds. Use a Unix Timestamp converter to obtain the exact date/time when the reset occurs. Optionally, you can refer to the `Retry-After` header value to know when to reattempt your request.
*-RateLimit-Limit	The maximum number of requests you're permitted to make.
Retry-After	The number of seconds after which API requests will be allowed again.

🚧
Multiple Rate Limits to Consider
The Govee APIs enforces rate limits per minute and per day. Therefore, please ensure your design does not violate these limit and when the limit is reach contains logic to throttle or honor the Retry-After value.

Per Day Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Per Minute Headers: API-RateLimit-Limit, API-RateLimit-Remaining, API-RateLimit-Reset

Sample HTTP Responses

HTTP/1.1 429 Too Many Requests
Date: Thu, 26 Jan 2023 14:50:08 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 41
Connection: close
Vary: Origin
Access-Control-Allow-Origin: *
API-RateLimit-Remaining: 0
API-RateLimit-Reset: 1674744661
API-RateLimit-Limit: 10
Retry-After: 52
X-Response-Time: 1ms
X-traceId: ba236bb0-9d88-11ed-a5ea-23b10dec5a12

Rate limit exceeded, retry in 53 seconds.

HTTP/1.1 200 OK
Date: Thu, 26 Jan 2023 15:09:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1716
Connection: close
Vary: Origin
Access-Control-Allow-Origin: *
API-RateLimit-Remaining: 9
API-RateLimit-Reset: 1674745800
API-RateLimit-Limit: 10
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9988
X-RateLimit-Reset: 1674795720
X-Response-Time: 109ms
X-traceId: 5ccfa340-9d8b-11ed-917c-fff28ff50e46

Handling 429 Status Code

Below is a rudimentary example of how to handle a 429 status code. You can adapt this example as a starting point to fit your use cases, coding standards, and best practices.

import requests
try:
    # Update to Valid Request
    response = requests.get(url, headers = headers)
    if response.status_code == 429:
        # Suspend Sending Additional Requests until the Retry-After period has elapsed
        time.sleep(int(response.headers["Retry-After"]))
    return response.content
except requests.exceptions.RequestException as e:
    return e