Skip to main content

​
burst_limit_exceeded

HTTP Status: 429 Too Many Requests

​
Example response

{
  "error": {
    "code": "burst_limit_exceeded",
    "message": "Per-minute request limit exceeded for your tier (free)",
    "docs_url": "https://docs.vatly.dev/errors/burst_limit_exceeded"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
The response includes a Retry-After header with the number of seconds left in the current 60-second window, plus X-Burst-Limit and X-Burst-Remaining (0).

​
What happened?

You’ve sent too many requests in a single minute. Burst limits protect the API from accidental tight loops and misconfigured clients.
TierBurst Limit (per minute)
Free20
Pro60
Business120

​
How to fix

  1. Wait the Retry-After seconds: The header contains the number of seconds remaining in the current 60-second window. Read it and back off accordingly
  2. Add a delay between requests: Space out your requests to stay within the per-minute limit
  3. Implement exponential backoff: On 429 responses, wait and retry with increasing delays
  4. Upgrade your tier: Higher tiers have higher burst limits

​
Common mistakes

  • Tight polling loops: Don’t call the API in a while(true) loop without delays
  • Ignoring Retry-After: Always read this header instead of guessing when to retry
  • Confusing with rate_limit_exceeded: Burst limits are per-minute; monthly limits are separate

​
Catching this error with the SDKs

import Vatly, { RateLimitError } from '@vatly/node';

const vatly = new Vatly('vtly_live_your_api_key');
const { data, error } = await vatly.vat.validate({ vatNumber: '...' });

if (error instanceof RateLimitError) {
  console.log(error.message);
  console.log(`Retry after ${error.retryAfter} seconds`);
}