Rate limits

Per-token, fixed 60-second windows. Headers on every response tell you exactly where you stand.

Tiers

Default applies to every newly-minted token. Partner is granted manually by FinzBooks admin; contact us if your integration needs it.

Headers

Every response includes:

X-RateLimit-Limit:      600
X-RateLimit-Remaining:  587
X-RateLimit-Reset:      1715492700

Reset is a Unix timestamp — the second your bucket refills.

When you hit the limit

HTTP/1.1 429 Too Many Requests
Retry-After: 28

{
  "code": "rate_limit.exceeded",
  "message": "Per-token rate limit exceeded. Retry after the window resets."
}

Honour Retry-After— it's the seconds until your bucket refills. Don't hammer.

Best practices

• Watch X-RateLimit-Remainingand back off when it's low rather than waiting for a 429.
• Use cursor pagination with per_page=200 for bulk reads — fewer requests, faster.
• Use the Idempotency-Keyheader so a transient 429 retry doesn't create duplicate resources.