---
title: "Rate limits"
description: "Read the rate-limit headers on every response, slow your client down before requests are refused, and design your integration so it never reaches the limit."
canonical_url: "https://twominutebilling.com/help/developers/api-essentials/rate-limits"
---
# Rate limits

> Read the rate-limit headers on every response, slow your client down before requests are refused, and design your integration so it never reaches the limit.

tmbilling counts your requests per API key, in fixed one-minute windows.

## Read the headers

Every authenticated response tells you where you are in the current window:

```http
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 573
X-RateLimit-Reset: 1789012800
```

`X-RateLimit-Reset` is a unix timestamp in seconds — when the window and your allowance reset.

Read `X-RateLimit-Remaining` and slow down before tmbilling refuses you. That works better for
both sides than discovering the limit by hitting it.

## Handle a 429

```http
HTTP/1.1 429
Retry-After: 18
```

```json
{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests"
  }
}
```

Wait `Retry-After` seconds, then send the request again.

<tip title="A 429 means tmbilling processed nothing">

Retry the request unchanged. With an `Idempotency-Key` you can retry even when you are unsure
whether it was processed — it was not.

</tip>

## Know the scope

The ceiling applies per key, so your integrations never eat each other's allowance. tmbilling sets
it per organization, so splitting traffic across more keys does not raise it. Ask us to raise the
limit instead.

## Design around the limit

- **Page with limit, not with concurrency.** One request for 500 rows costs one unit. Fifty
requests for ten rows cost fifty.
- **Use webhooks instead of polling.** An endpoint receiving `invoice_paid` costs you nothing per
minute. A poller asking "is it paid yet?" every second spends your whole budget. See
[Webhooks](https://twominutebilling.com/help/developers/webhooks).
- **Back off on the header, not on the error.** By the time you read a `429`, you have already
lost a request.

## Related

- [Webhooks, so you do not need to poll](https://twominutebilling.com/help/developers/webhooks)


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.