Home / Use cases / Node.js

VAT API Rate Limiting & Caching: Production Best Practices

Optimise VAT API usage with effective caching and rate limit management. Covers in-memory cache, Redis distributed cache, request deduplication, quota tracking, and graceful 429 handling.

Implementation steps

1. 1

   Add in-memory caching for single-instance apps

   Create a Map-based cache in your VatValidator service class. On each validation call, check the cache for a recent result (under 23 hours old) before calling the API. Only cache 'active' and 'inactive' results — do not cache 'service_unavailable', as the registry may recover before your 23-hour TTL expires.

2. 2

   Upgrade to Redis for multi-instance deployments

   Replace the in-memory Map with an Upstash Redis client (REST API works in serverless). Use setex with a TTL of 82800 seconds (23 hours). Use the normalised VAT number (uppercase, spaces stripped) as the cache key prefixed with 'vat:'. The TaxID API marks cached responses with cached: true — combine your Redis cache hit with the API's own caching for maximum efficiency.

3. 3

   Implement request deduplication

   Add a pendingRequests Map that stores in-flight Promise<VatResult> objects keyed by the normalised VAT number. Before making an API call, check if a request is already in flight for the same key. If so, return the existing Promise instead of making a new API call. Remove the key from the map when the Promise resolves (in both success and error cases).

4. 4

   Track quota usage

   Count every outgoing TaxID API call (not cache hits) in a database counter. Use a monthly bucket key (e.g., 'vat_calls:2026-06') and increment it with each real API call. Alert your team when you reach 80% of your plan limit. This gives you time to upgrade or investigate unexpected usage spikes before hitting the hard limit.

5. 5

   Handle 429 with exponential backoff

   Wrap your API call in a retry loop that detects HTTP 429 responses and backs off exponentially: wait 1000ms, then 2000ms, then 4000ms, for a maximum of 3 retries. Log every 429 with the affected VAT number, current timestamp, and retry attempt number. If all retries exhaust, return service_unavailable — never throw an unhandled error to the caller for rate limit responses.

Code example

const res = await fetch(
  'http://localhost:3000/api/v1/validate/DE/DE123456789',
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const { valid, status, company_name, company_address } = await res.json();

if (valid) {
  console.log(`Valid EU business: ${company_name}`);
} else if (status === 'service_unavailable') {
  // VIES is temporarily down — retry or allow with manual check
  console.log('VIES unavailable — check back in a few minutes');
} else {
  console.log('Invalid VAT number — charge local tax rate');
}

import requests

res = requests.get(
    "http://localhost:3000/api/v1/validate/DE/DE123456789",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = res.json()

if data["valid"]:
    print(f"Valid: {data['company_name']}")
elif data["status"] == "service_unavailable":
    print("VIES temporarily unavailable")
else:
    print("Invalid VAT number")

API response

The TaxID API returns a consistent JSON response for every validation request:

{
  "valid": true,
  "status": "active",
  "country_code": "DE",
  "vat_number": "123456789",
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin",
  "request_date": "2026-05-10T00:00:00.000Z",
  "cached": false,
  "request_id": "req_01j..."
}

Error handling

The API uses a consistent Stripe-style error format. Always handle service_unavailable separately — VIES has occasional downtime and you should not reject valid customers during outages.

Related use cases