Telm meters the API in two ways: a per-minute rate limit (a burst ceiling) and a daily quota (your total budget for the UTC day). Both scale with plan. Every metered response returns X-Quota-Limit, X-Quota-Used and X-Quota-Reset so you always know your remaining budget, and both limits return 429 with a Retry-After header when exceeded.
1Two limits: per-minute rate and daily quota
There are two separate ceilings. The per-minute rate limit caps how many requests you can make within any single minute, smoothing out bursts. The daily quota is your overall budget: it caps how many metered calls you can make across the whole UTC day.
They are independent. You can hit the per-minute limit while still having plenty of daily quota left (you are simply sending too fast), or exhaust your daily quota while well under the per-minute limit (you have used up the day). Both return a 429 status, but for different reasons — check the error code in the body to tell them apart.
- Per-minute rate limit — a burst ceiling, resets every minute.
- Daily quota — your total metered calls for the day, resets at midnight UTC.
- The quota is counted once per account, shared across all of your keys.
2Daily quota by plan
Your daily quota is the number of metered API calls you can make per UTC day, and it depends on your plan. The counter is shared across all of your keys and follows the best plan among the groups you administer — with no paid subscription, you are on the Free tier.
The window is the UTC calendar day, so your used counter resets to zero at midnight UTC. A batch spam check costs one call per item in the batch, not one call for the whole request.
- Free — 100 calls per day.
- Basic — 1,000 calls per day.
- Pro — 10,000 calls per day.
- Business — 50,000 calls per day.
3Per-minute rate limit by plan
On top of the daily quota, each API key is limited to a number of requests per minute according to its plan tier. This is a smoothing limit: it stops a single client from sending a huge spike in one second, even when the daily budget is far from spent.
Separately, broad per-IP and per-account ceilings apply across the whole API to keep the platform stable. In normal use — steady, paced requests — you will never touch these; they only trigger on abusive bursts.
- Free and Basic — 60 requests per minute.
- Pro — 600 requests per minute.
- Business — 1,800 requests per minute.
- Spread requests out rather than firing them all at once.
4Reading your remaining budget
You never have to guess how much quota is left. Every metered response — success or failure — includes three headers: X-Quota-Limit (your daily limit), X-Quota-Used (how many calls you have spent today), and X-Quota-Reset (the moment, in UTC, when the counter resets).
The spam-check endpoints also echo the same numbers inside the response body under a quota object, so you can read your remaining budget without parsing headers. Use these to pace your own requests and to warn yourself before you run out.
- X-Quota-Limit — your daily call limit.
- X-Quota-Used — calls spent so far today.
- X-Quota-Reset — reset time in UTC (RFC 3339).
- The spam-check responses also include a quota object with the same fields.
5What happens at 429
When you cross either limit, the API returns HTTP 429 with a Retry-After header telling you how many seconds to wait. For the per-minute rate limit, Retry-After is about a minute. For the daily quota, the body carries a daily_quota_exceeded code plus your plan, limit, used count, the reset time, and an upgrade hint, and Retry-After counts down to midnight UTC.
The right way to handle 429 is to back off and retry after the Retry-After delay, not to hammer the endpoint. Well-behaved clients read the header and pause; clients that keep retrying immediately just stay blocked.
- 429 rate_limit_exceeded — you sent too fast; wait about a minute.
- 429 daily_quota_exceeded — the day is used up; wait until the UTC reset or upgrade.
- Always respect the Retry-After header before retrying.