API & Rate Limits

API & Rate Limits

Endpoints Used

This integration uses all 5 available API endpoints of the Kachelmann v02 API:

Endpoint	Purpose	Fields
/current/{lat}/{lon}	Current weather conditions	15
/forecast/{lat}/{lon}/advanced/1h	Hourly forecast (24h)	22
/forecast/{lat}/{lon}/advanced/6h	6-hourly forecast (~10 days)	24
/forecast/{lat}/{lon}/trend14days	14-day trend with probabilities	29
/tools/astronomy/{lat}/{lon}	Sun/moon rise/set, moon phase	16

All endpoints are fetched in parallel using asyncio.gather for maximum speed.

Rate Limits

Hobby Plan (Plus subscription)

Metric	Value
Daily request limit	700 requests
Requests per update	5 (one per endpoint)
Default interval (10 min)	~720 requests/day ⚠️
Recommended interval (15 min)	~480 requests/day ✅
Safe interval (20 min)	~360 requests/day ✅

Calculation

requests_per_day = (24 * 60 / update_interval_minutes) * 5

Interval	Requests/day	Status
5 min	1440	❌ Way over limit
10 min	720	⚠️ Slightly over
12 min	600	✅ OK
15 min	480	✅ Comfortable
20 min	360	✅ Very safe
30 min	240	✅ Minimal usage

Recommendation

Set the update interval to 900 seconds (15 minutes) for a good balance between freshness and API budget.

Rate Limit Tracking

The integration tracks rate limit headers from API responses:

• X-RateLimit-Remaining → sensor.kachelmannwetter_api_requests_remaining
• X-RateLimit-Limit → stored internally

Enable the diagnostic sensor to monitor your usage:

1. Go to the KachelmannWetter device
2. Find "API requests remaining" (disabled by default)
3. Enable it

Rate Limit Exceeded (HTTP 429)

When the API returns 429:

1. The integration reads the Retry-After header
2. Logs a warning with the retry delay
3. Schedules an automatic retry after the specified delay
4. Raises UpdateFailed so HA shows the entity as unavailable temporarily

No manual intervention needed — it recovers automatically.

Authentication Errors

HTTP Status	Meaning	Action
401	Invalid API key	Reauth flow triggered
403	Location not configured	Check API location settings on kachelmannwetter.com

Request Timeout

All API requests have a 10-second timeout. If the API is slow or unreachable, the update fails gracefully and retries at the next interval.

API Documentation

Official API docs: api.kachelmannwetter.com/v02/_doc.html