Fix default polling interval to prevent API rate limiting

[ulfschnabel]

Fix default polling interval to prevent API rate limiting

Problem

The current default polling interval of 10 seconds causes users to hit Govee's API rate limit with just a few devices. This is the root cause of many rate limit issues reported in #106, #107, #129, #190, and others.

Why 10 seconds is too aggressive:

Govee API Limit: 10,000 requests per 24 hours

Current behavior (10s polling):

• Daily requests = (86,400 seconds ÷ 10s interval) × device count
• With just 4 devices: 8,640 × 4 = 34,560 requests/day
• This exceeds the limit by 3.5x! ❌

Real-world impact:

• Users hit rate limits within hours of setup
• Lights become unavailable and show AttributeError
• Integration appears "broken" to new users
• Multiple GitHub issues and frustrated users

Solution

This PR changes the default polling interval from 10s → 300s (5 minutes) and adds validation warnings for low intervals.

New behavior (300s polling):

With 300s (5 minute) default:

• Daily requests = (86,400 ÷ 300) × device count
• With 4 devices: 288 × 4 = 1,152 requests/day ✅
• With 30 devices: 288 × 30 = 8,640 requests/day ✅
• Safely under the 10,000 limit!

API Usage Calculator:

Devices	10s (old)	60s	300s (new)	Result
1	8,640	1,440	288	✅ Safe
4	34,560	5,760	1,152	✅ Safe
10	86,400	14,400	2,880	✅ Safe
30	259,200	43,200	8,640	✅ Safe

Changes Made

1. config_flow.py

• Changed default from default=10 → default=300 (lines 85 and 175)
• Added validate_delay() function that logs warnings for intervals < 60s
• Calculates estimated device limit for chosen interval
• Example warning: "With 10s polling, you'll hit the limit with ~3 devices"

2. translations/en.json

• Updated field description to explain it's in seconds
• Added API rate limit information with examples
• Included calculation formula for users to estimate their usage
• Clarified that "assumed state" provides instant UI feedback

Backward Compatibility

✅ Existing installations unchanged - Only affects new configurations
✅ Users can still choose any value - No hard restrictions added
✅ Warning-only approach - Logs info but doesn't block configuration

User Experience Improvements

Before:

• Install integration with default settings
• Hit rate limit within hours
• Lights show unavailable/errors
• User confused, files GitHub issue

After:

• Install integration with 300s default
• Never hit rate limit under normal use
• Lights stay available
• If user chooses < 60s, clear warning logged about device limits

Complements Existing Features

This works perfectly with the existing "use_assumed_state" option (enabled by default):

• Background polling (300s): Verifies actual state periodically
• Assumed state: UI updates instantly when controlling lights
• Best of both worlds: Instant feedback + low API usage

Users can also implement "poll on state change" automations for immediate verification after controls (as documented in issue discussions).

Testing

Tested with:

• ✅ New installation: Defaults to 300s, no rate limits
• ✅ Existing installation: Keeps previous value
• ✅ Options flow: Shows current value, accepts changes
• ✅ Low interval warning: Logs correctly with < 60s
• ✅ 4 devices @ 300s = 1,152 requests/day (monitoring confirmed)

Related Issues

Fixes/Addresses:

• Rate Limit Exceeded #106 - Rate Limit Exceeded
• rate limited! the limit is 10000 requests every 24 hours #107 - rate limited! the limit is 10000 requests
• Rate limited! the limit is 10000 requests every 24 hours. #129 - Rate limited! the limit is 10000 requests every 24 hours
• API Limit Keeps getting hit #190 - API Limit Keeps getting hit
• Rate limit exceeded #78 - Rate limit exceeded
• Different Polling Intervals for Different Devices  #32 - Different Polling Intervals for Different Devices (partial - better default)

Additional Context

The 10-second default was likely set before the 10,000/day limit existed or became strictly enforced. Govee has gotten stricter with rate limiting over time, making the old default problematic.

With modern Home Assistant's "assumed state" feature, users get instant UI feedback regardless of polling interval, so there's no UX downside to longer intervals.

---

This single change will prevent the majority of rate limit issues users encounter and make the integration work reliably out of the box.