Rate Limits

Tier rate limits, 429 handling, and retry strategies.

Rate Limits by Tier

Each pricing tier has a per-minute rate limit and a monthly request quota:

| Tier | Rate Limit | Monthly Quota | Overage | |------|-----------|---------------|---------| | Free | 10 req/min | 50 req/month | Blocked (no overage) | | Starter | 60 req/min | 1,000 req/month | $0.03/request | | Growth | 300 req/min | 25,000 req/month | $0.01/request | | Enterprise | Custom | Unlimited | Custom |

Rate Limit Headers

Every API response includes rate limit headers:

Code

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1711893600

X-RateLimit-Limit -- Maximum requests per minute
X-RateLimit-Remaining -- Requests remaining in the current minute window
X-RateLimit-Reset -- Unix timestamp when the current window resets

Handling 429 Responses

When you exceed the rate limit, the API responds with 429 Too Many Requests:

Code

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 45 seconds."
  }
}

The response includes a Retry-After header with the number of seconds to wait.

Monthly Quota

Your monthly quota resets on the first day of each billing period. You can track your quota usage in the dashboard or via the usage API:

Code

curl "https://api.aribatax.com/v1/usage" \
  -H "X-API-Key: your_api_key_here"

On the Free tier, requests beyond the monthly quota are blocked with 429. On paid tiers, overage requests are allowed but billed at the per-request overage rate for your tier.

Retry Strategy

For 429 responses, use the Retry-After header:

Code

async function fetchWithRateLimit(url: string, apiKey: string): Promise<Response> {
  const res = await fetch(url, {
    headers: { "X-API-Key": apiKey },
  });

  if (res.status === 429) {
    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "60", 10);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRateLimit(url, apiKey); // Retry once
  }

  return res;
}

Usage Alerts

Configure usage alerts in the dashboard to get notified when your quota reaches 80%, 100%, or any custom threshold. Alerts can be sent via email or webhook.

Tips

Batch requests where possible instead of making many individual lookups
Cache responses for data that does not change frequently (parcel geometry, county lists)
Use webhooks for usage alerts instead of polling the usage endpoint
Contact us for custom rate limits if your use case needs more than 300 req/min