Rate Limits

Three limits apply to requests to the Sporeline API. There is no monthly request quota on any plan.

Per-Address Limit

The API’s firewall counts requests from each IP address over a rolling 5-minute window. Once an address goes over 300 requests in that window, its requests are blocked with 403 until its rate falls back under the limit.

300 requests in 5 minutes averages out to one request per second. For most integrations, this is the limit you’ll meet first.

The count covers everything sent from that address, so if your integration shares an internet connection with people using the Sporeline app, their requests count too.

API Throttle

The API as a whole accepts 25 requests per second, and absorbs short bursts of up to 50. This limit is shared by every account and every caller, not set per key. Requests over it return 429.

A few endpoints that don’t need authentication, such as sign-up, have tighter limits of their own. They don’t affect requests made with an API key.

Busy Endpoints

Each part of Sporeline can only work on so many requests at the same moment. When a burst of requests reaches one that is already full, the extra requests get 503 with a Retry-After: 2 header and the usual error envelope, with the code SERVICE_UNAVAILABLE and "retry": true. A request turned away like this was not run, so wait the number of seconds in Retry-After and send it again. The same answer also comes back when a request runs too long and is cut off, so a write needs the care described under Handling a Limit Response.

Staying Under the Limits

• Send requests one at a time, or a few at a time. Large parallel bursts are the quickest way to hit either limit.
• Fetch bigger pages. Where a list endpoint accepts a limit parameter, a larger page means fewer requests. Follow next_token to get the next page.
• Poll only as often as you need. Every request counts toward the per-address limit.

Handling a Limit Response

Check the HTTP status code rather than the response body. The first two limits are enforced before the request reaches Sporeline, and their responses don’t follow the usual error envelope reliably.

• 429: wait and retry with exponential backoff, for example after 1, 2, 4 and 8 seconds, with a little random jitter added.
• 503 with "retry": true on a read: wait for the number of seconds in the Retry-After header, then send the request again.
• 503 with "retry": true on a create or other write: the same answer is given when a request takes too long and is cut off, and that request may already have been saved. Only resend it automatically when the endpoint honours an Idempotency-Key (the API reference lists which do) and you send the same key again. Otherwise, check whether the first request was saved before you send it again.
• 403 on requests that normally succeed: your address may be over the per-address limit. Stop sending for a few minutes, then resume at a lower rate. A 403 can also mean your key’s role isn’t allowed to do what you asked, so check the request if it keeps failing after a pause.

AI Assistant Connections

When you connect an AI assistant such as ChatGPT or Claude to your farm, each action the assistant takes in Sporeline counts as one call. Two limits apply to those calls, on top of the limits above.

Only actions count. Connecting, and the assistant looking up which actions it can use, are free.

When a limit is reached, the assistant gets an error with the code rate_limited instead of an answer, and usually tells you so in the chat:

• Per-person limit: “This connection has made 60 calls in the last minute. Wait a moment and try again.” The count starts over at the next minute, so wait a few seconds and ask again.
• Daily farm limit: “This farm has used its AI assistant calls for today.” The count resets at midnight UTC (8 p.m. Eastern during daylight time, 7 p.m. otherwise). People can keep using Sporeline itself in the meantime.

The error also carries retry_after_seconds, the number of seconds until the limit resets, for anyone building their own client.

Related Pages

• Authentication: API keys and the Authorization header
• Error Codes: every error status and code
• API Reference: base URL, response format and endpoints