Are there rate limits or a per-second cap?

There is no per-second or per-minute rate limit today – the only limit is your monthly quota. You can send requests as fast as your integration needs; vatnode throttles by monthly volume, not by short-window bursts.

How you track your quota

Each live response to GET /v1/vat/:vatId carries headers that show where you stand:

• RateLimit-Limit – your plan’s monthly base quota.
• RateLimit-Remaining – requests left in the current monthly window after this one.
• RateLimit-Reset – Unix epoch seconds at which the window resets.
• Vatnode-Quota-Warning – a plain-text nudge that appears once usage reaches about 80% of the quota. It is sent only on the Free plan, which stops at its limit; Starter and Pro keep processing past the quota and get the RateLimit-* headers without the warning.

The RateLimit-* headers appear on both the 200 response and the 429 quota-exceeded response. They are not sent in test mode, because test keys never touch your quota, and they are omitted on unlimited plans, where there is no ceiling to report.

The only 429

A 429 with the RATE_LIMITED code is returned only when a plan with a hard cap has used up its monthly quota. It is never a signal to slow down and retry in a second. Starter and Pro don’t return it under normal use, since requests past the included quota are billed as overage instead.

What to do with the headers

Log RateLimit-Remaining next to your requests and alert yourself when it gets low. A quick check is remaining / limit below a threshold you choose. Full header semantics, an example response and code samples are in the rate limits reference; how errors look is in the error reference.