> ## 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 Limits

> Tier-based rate limiting and quota headers

# Rate Limits

Avatcado uses tier-based monthly rate limits. Every authenticated response includes rate limit headers so you always know where you stand.

## Tiers

| Tier         | Monthly Requests | Burst Limit (per minute) | Consultation Number |
| ------------ | ---------------- | ------------------------ | ------------------- |
| **Free**     | 500              | 20                       | Yes                 |
| **Pro**      | 10,000           | 60                       | Yes                 |
| **Business** | 50,000           | 120                      | Yes                 |

## Rate limit headers

Validation responses include these headers on 2xx and monthly-quota 429 paths. Burst 429 responses include only `X-Burst-Limit`, `X-Burst-Remaining`, and `Retry-After`. Rate routes (`/v1/rates`) return only `X-Burst-*` (they do not count against monthly quota). Test-mode responses return no rate-limit headers.

| Header                  | Description                                                                                                                                          | Example                    |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `X-RateLimit-Limit`     | Total requests allowed this period                                                                                                                   | `10000`                    |
| `X-RateLimit-Remaining` | Requests remaining this period                                                                                                                       | `9542`                     |
| `X-RateLimit-Reset`     | When the quota resets (ISO 8601). Free tier: 1st of next month. Paid tiers: billing anniversary                                                      | `2026-04-20T00:00:00.000Z` |
| `X-Burst-Limit`         | Per-minute burst limit for your tier                                                                                                                 | `60`                       |
| `X-Burst-Remaining`     | Burst requests remaining this minute                                                                                                                 | `58`                       |
| `Retry-After`           | Seconds to wait before retrying (only on 429/503). Burst: remaining seconds in the current 60-second window. Monthly: seconds until the period reset | `1`-`60` or `86400`        |

## Monthly reset

* **Free tier**: quotas reset on the **first day of each month at 00:00 UTC**.
* **Pro and Business tiers**: quotas reset on your **billing anniversary**. If you subscribe on March 20th, your quota resets on the 20th of each month.

The `X-RateLimit-Reset` header always reflects your next reset date.

## Burst limits

In addition to monthly quotas, each tier has a per-minute burst limit. This protects the API from accidental tight loops and misconfigured clients.

When you exceed the burst limit, the API returns a `429` status with the [`burst_limit_exceeded`](/errors/burst_limit_exceeded) error and a `Retry-After` header equal to the remaining seconds in the current 60-second window.

## What happens when you hit the monthly limit

When your monthly quota is exhausted, the API returns a `429` status with the [`rate_limit_exceeded`](/errors/rate_limit_exceeded) error:

```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 `X-RateLimit-Remaining` header will be `0` and `X-RateLimit-Reset` will tell you when your quota refreshes. The `Retry-After` header contains the number of seconds until the monthly reset.

<Note>
  Cached responses also count toward your monthly usage. See [Caching](/caching) for details.
</Note>

## Batch validation usage

[Batch requests](/batch-validation) charge based on the number of **unique** VAT numbers in the request. Duplicates within a single batch are free.

* A batch of `["NL123456789B01", "NL123456789B01", "DE987654321"]` consumes **2** requests from your monthly quota
* The entire batch is **rejected** with `rate_limit_exceeded` if your remaining quota is less than the unique count. No partial execution occurs.
* Each batch request counts as **1 hit** against the per-minute [burst limit](#burst-limits), regardless of how many VAT numbers it contains

## Test keys

Test keys (`avat_test_` prefix) are **exempt from monthly quota and burst limits**. They don't consume quota, don't trigger 429s, and don't return rate limit headers. Async endpoints reject test keys; use a live key for async testing. See [Test Mode](/test-mode) for details.

## Non-billable failures

When the upstream validation service is unreachable AND no cached or stale response can be served, the API returns a `503` with one of:

* [`upstream_unavailable`](/errors/upstream_unavailable): the upstream provider (VIES, HMRC, BFS, BRREG, ABR) returned an error or did not respond
* [`upstream_member_state_unavailable`](/errors/upstream_member_state_unavailable): VIES is up but the specific member state is unreachable

These two `503` responses do **not** count toward your monthly quota. The quota is automatically refunded when no usable answer was returned. The `X-RateLimit-Remaining` header on subsequent requests reflects the refund.

If a [stale cached response](/caching#stale-fallback) was served instead (HTTP `200` with `meta.stale: true`), the request **does** count, since you received data.

Other failure types (`invalid_vat_format`, `unsupported_country`, `tier_insufficient`, etc) are 4xx errors and are not refundable.