Rate Limit & Quota Headers

vatnode throttles by monthly quota, not by requests per second. Every VAT validation response tells you where you stand against that quota through standard response headers — so you can see the ceiling approaching in your own logs, long before a request is ever refused.

The headers use the IETF draft RateLimit-* names (unprefixed), not the deprecated X-RateLimit-* convention. They appear on GET /v1/vat/:vatId responses for live keys only.

The Headers

Header	Type	Meaning
RateLimit-Limit	integer	Your plan's monthly base quota — the total number of included live validations.
RateLimit-Remaining	integer	Requests left in the current monthly window after this one, computed as `max(limit − used − 1, 0)` — this request has already reserved its slot.
RateLimit-Reset	integer	Unix epoch seconds at which the current monthly quota window resets and your remaining count returns to the full limit.
Vatnode-Quota-Warning	string	A human-readable upgrade nudge, present only once usage reaches ~80% of the quota. See When the warning appears below.

When Each Header Appears

The three RateLimit-* headers are emitted on both the 200 success response and the 429 quota-exceeded response, so you can read your position whether or not the request went through.
They are omitted for unlimited plans (enterprise and internal) — there is no ceiling to report against.
They are not emitted in test mode. Test keys never touch your quota, so there is nothing to count.

When the warning appears

Vatnode-Quota-Warning is deliberately narrow. It appears only when all of the following hold:

The response is a 200 — the request was allowed. It is never attached to the 429.
Usage has reached 80% or more of the monthly quota.
You are on a hard-capped plan — the free plan, whose 100-request monthly quota stops live calls at 100%. On overage plans (Starter, Pro) calls past the quota are billed and never interrupted, so an “upgrade” nudge would be misleading — those plans get the RateLimit-* headers but no warning.

The value is a plain string safe to log verbatim:

Vatnode-Quota-Warning

82% of monthly quota used; upgrade at https://vatnode.dev/dashboard/billing

Example Response

A successful validation on the free plan, once usage has crossed the warning threshold:

200 OK — free plan near its quota

HTTP/1.1 200 OK
Content-Type: application/json
RateLimit-Limit: 100
RateLimit-Remaining: 17
RateLimit-Reset: 1782777600
Vatnode-Quota-Warning: 82% of monthly quota used; upgrade at https://vatnode.dev/dashboard/billing

{
  "valid": true,
  "vatId": "IE6388047V",
  "countryCode": "IE",
  "companyName": "GOOGLE IRELAND LIMITED",
  "source": "VIES",
  "consultationNumber": "WAPIAAAAW1234567"
}

Using Them as an Upgrade Signal

Because the signal rides on every response, you don't need a separate polling job to know when you're running out of headroom. Two simple patterns:

1. Watch for the warning header in your logs

The presence of Vatnode-Quota-Warning is itself the trigger — no threshold maths on your side. Surface it to whoever owns the account.

JavaScript

const response = await fetch(url, options)

const warning = response.headers.get('Vatnode-Quota-Warning')
if (warning) {
  // e.g. page an on-call channel, or flag it in your billing dashboard
  console.warn('vatnode quota nearing limit:', warning)
}

2. Track the raw counters on every plan

Overage plans never receive the warning, so if you want an early signal there too, derive it yourself from RateLimit-Remaining and RateLimit-Limit:

JavaScript

const limit = Number(response.headers.get('RateLimit-Limit'))
const remaining = Number(response.headers.get('RateLimit-Remaining'))

if (limit && remaining / limit < 0.1) {
  console.warn(`vatnode: only ${remaining} of ${limit} monthly requests left`)
}

When the free quota does run out, the endpoint returns 429 with the RATE_LIMITED error code. See Error Handling for how to handle that response, and your billing dashboard to move onto a plan that bills overage instead of blocking.