From Honeymoon to Reality, The Home Connect API and the Hidden Cost of Rate Limiting

Yesterday I wrote about how much of a pleasure it is to work with the Home Connect API, and I stand by that. The developer portal is well structured, the endpoints are predictable, and getting a first prototype running is surprisingly quick.

But every honeymoon ends, mine did when I stumbled across the rate limiting rules, not up front in the introduction, but buried deep in the documentation.

What I Found

Home Connect enforces two different types of rate limits:
- Amount-based: 10 requests per second on average, 20 max burst.
- Time-based: 50 requests per minute, 1000 requests per day, and strict quotas on token refreshes.

Some of these are generous, but others can trip you up faster than expected. If you naïvely poll every few seconds, you will hit the daily cap before you know it. Worse, if you refresh tokens too often you can burn through your allowance long before midnight. The documentation even warns that clients may be blocked if they regularly exceed the thresholds.

And sometimes the API does not just block you, it instructs you to wait. My log read: 

```
Rate limited (429). Sleeping 70300.8s (Retry-After='70300')
```

That is more than 19 hours of doing nothing.

Why It Matters

For my test setup with two appliances, polling status every five minutes seems harmless. But the math quickly adds up. Two devices, 12 polls per hour, 24 hours a day, that is 576 requests per day. Add extra endpoints like /programs/active and you are within touching distance of the 1000 per day ceiling.

This is not a “developer sandbox” problem, this is production reality. An integration that feels rock-solid for weeks can suddenly fail with HTTP 429 “Too Many Requests”, leaving dashboards blank and appliances “offline.”

Coping Strategies

  1. Cache aggressively, do not call /homeappliances every loop, only refresh once per hour or less.
  2. Back off on 429s, respect the Retry-After header, but cap absurd waits.
  3. Count your calls, keep rolling counters for per-minute and per-day usage and self-throttle before the server does.
  4. Use monitoring channels, Home Connect provides event streams. They count as one long-lived connection, not hundreds of polls. For live updates this is the only sustainable option.
  5. Be careful with token refresh, do not spawn multiple processes refreshing the same credentials. Share one tokens.json across your scripts.

The Takeaway

The Home Connect API is still a joy to use, but it is a joy with guardrails. If you treat it like a firehose you will get cut off. If you treat it with care, caching, backoff, monitoring, it will happily power your dashboards and automations for the long run.