> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avatcado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# rate_limit_exceeded

> Error: monthly quota exhausted

# rate\_limit\_exceeded

<Info>HTTP Status: **429 Too Many Requests**</Info>

## Example response

```json theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Monthly request limit exceeded for your tier (free)",
    "docs_url": "https://docs.avatcado.com/errors/rate_limit_exceeded"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

The response will also include rate limit headers and a `Retry-After` header:

```
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-04-01T00:00:00.000Z
Retry-After: 172800
```

For paid tiers, `X-RateLimit-Reset` reflects your billing anniversary instead of the 1st of the month.

## What happened?

You've used all the requests in your monthly quota. This happens when:

* Your cumulative requests this month have reached your tier's limit
* Cached responses have counted toward your usage (cached results still consume quota)

## How to fix

1. **Wait for the reset**: Check the `Retry-After` header for the number of seconds to wait, or `X-RateLimit-Reset` for the exact reset timestamp (your billing period reset date)

2. **Upgrade your tier**: Move to a higher tier for more monthly requests:

   | Tier     | Monthly Limit |
   | -------- | ------------- |
   | Free     | 500           |
   | Pro      | 10,000        |
   | Business | 50,000        |

3. **Optimize your usage**: Implement client-side caching to avoid duplicate lookups for the same VAT number

## Common mistakes

* **Not tracking usage**: Monitor the `X-RateLimit-Remaining` header on each response to see how many requests you have left
* **Assuming cached results are free**: Cached responses still count toward your monthly quota
* **Ignoring the reset date**: The `X-RateLimit-Reset` header tells you exactly when your quota refreshes

## Catching this error with the SDKs

<CodeGroup>
  ```typescript @avatcado/node theme={null}
  import Avatcado, { RateLimitError } from '@avatcado/node';

  const avatcado = new Avatcado('avat_live_your_api_key');
  const { data, error } = await avatcado.vat.validate({ vatNumber: '...' });

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

  ```python Python theme={null}
  from avatcado import Avatcado, RateLimitError

  avatcado = Avatcado("avat_live_your_api_key")

  try:
      result = avatcado.vat.validate("...")
  except RateLimitError as e:
      print(e.message)
      print(f"Retry after {e.retry_after} seconds")
  ```
</CodeGroup>

## Related errors

* [`burst_limit_exceeded`](/errors/burst_limit_exceeded) - Per-minute burst limit exceeded (different from monthly quota)
* [`unauthorized`](/errors/unauthorized) - API key is invalid (different from being rate limited)