API essentials

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:

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/1.1 429
Retry-After: 18

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

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

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

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.
  • Back off on the header, not on the error. By the time you read a 429, you have already lost a request.

Related

Pagination

Page through any list with cursors, filter it with one field[operator]=value grammar, and sort or search it. There is no catch-all filter parameter to guess.

Versioning

Pin a date-based API version with a header, learn which changes arrive additively within a version, and know when to expect a new version and a deprecation.

Copyright © 2026