spooly.eu/docs/limits

Limits

The limits stop automations that run in circles. For comparison: the Home Assistant integration needs about 1,450 calls a day.

Open as text

On this page

Values

Limit	Value	Code
Calls	10,000 a day per account, across all connections combined. The day ends at midnight (UTC).	`fair_use`
At once	4 requests per account. There are also limits that all accounts share: 12 requests together, and during the key check 16 together and 4 per IP address. Above that, the API answers right away with Retry-After: 1.	`too_many_parallel`
Request size	At most 64 KB for `/api/v1` and `/api/spoolman`. Spooly rejects larger requests with 413 without reading them.	no code, see error codes
Changes per minute	60 per connection	`change_rate_limit`
Changes per day	500 per connection	`change_daily_limit`
New spools per day	100 per connection	`new_spool_daily_limit`
New keys	30 per hour per account	`too_many_keys`

What counts

Every valid request counts as a call, including the one an AI uses to fetch its tool list.
Failed changes do not count against the change limits.
GET /me shows today’s count in calls_today and daily_limit.

How your program should react

All limits answer with 429. The wait in seconds is in the Retry-After header. Wait at least that long, then retry. With fair_use, it only continues after midnight (UTC).

too_many_parallel can also hit you when others are sending a lot right now, even if you send little yourself. Wait briefly and repeat the request.

Do not let an automation write on every reading. A scale that reports ten times a second needs a condition that waits for a steady value.