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

# FraudTrace AI API Rate Limits and Throughput Guidance

> Learn how FraudTrace AI enforces rate limits, read response headers, handle 429 errors, and maximize throughput with the batch endpoint.

The FraudTrace AI API enforces rate limits to ensure fair usage and maintain consistent performance for all customers. Limits are applied per API key, so each key you create operates within its own independent quota. This page explains how to read the rate limit headers returned on every response, how to handle a `429 Rate Limit Exceeded` error gracefully, and how to structure your integration to get the most throughput out of your plan.

## Rate Limit Tiers

Rate limits vary by plan. Your exact limits depend on the tier associated with your API key — contact the FraudTrace AI team or check your dashboard to confirm the specific values for your account.

<Info>
  If you need higher throughput than your current plan provides — for example, during a bulk screening project or a production traffic spike — reach out to the FraudTrace AI team to discuss a limit increase.
</Info>

## Rate Limit Response Headers

Every API response includes the following headers so you can monitor your quota in real time and take action before you hit the limit.

| Header                  | Type           | Description                                                        |
| ----------------------- | -------------- | ------------------------------------------------------------------ |
| `X-RateLimit-Limit`     | Integer        | Total requests allowed in the current window                       |
| `X-RateLimit-Remaining` | Integer        | Requests remaining in the current window                           |
| `X-RateLimit-Reset`     | Unix timestamp | Time at which the current window resets and your quota is restored |

### Example Response Headers

The response below shows a key that has consumed 153 of its 1,000 requests in the current window, with the window resetting at Unix timestamp `1712345678`.

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1712345678
```

You can verify this with `curl -i`, which prints response headers before the body:

```bash theme={null}
curl -i --request GET \
  --url "https://api.fraudtraceai.com/v1/verify/upi?upi=user@upi" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

<Tip>
  Build proactive monitoring around `X-RateLimit-Remaining`. If it drops below a threshold that matters to your workload, slow your request rate before you hit zero — this avoids the latency penalty of waiting out a `429` backoff.
</Tip>

## When You Exceed the Limit

When your request count exceeds the allowed limit, the API returns an HTTP `429 Too Many Requests` response. The response body follows the standard error format and includes a `retry_after` field, and the response headers include `Retry-After`, both indicating how many seconds to wait before sending another request.

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your request limit. Please retry after 14 seconds.",
  "retry_after": 14
}
```

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 14
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678
```

<Warning>
  Do not immediately retry after a `429`. Wait at least the number of seconds specified by the `Retry-After` header before sending your next request. Sending requests before the window resets will continue to return `429` and will not restore your quota faster.
</Warning>

## Handling 429 in Python

The function below reads the `Retry-After` header on a `429` response and waits the appropriate amount of time before retrying. It falls back to an exponential delay if the header is absent.

```python theme={null}
import time
import requests

def verify_upi_with_retry(vpa: str, api_key: str, max_retries: int = 3) -> dict:
    for attempt in range(max_retries):
        resp = requests.get(
            "https://api.fraudtraceai.com/v1/verify/upi",
            params={"upi": vpa},
            headers={"Authorization": f"Bearer {api_key}"},
        )

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Waiting {retry_after}s before retry {attempt + 1}/{max_retries}.")
            time.sleep(retry_after)
            continue

        resp.raise_for_status()
        return resp.json()

    raise Exception("Rate limit exceeded after maximum retries. Consider reducing request rate or upgrading your plan.")
```

## Burst vs. Sustained Throughput

Most plans distinguish between **burst throughput** — the number of requests you can fire in a short spike — and **sustained throughput** — the average rate you can maintain over a longer window (e.g. per minute or per hour).

* **Burst headroom** is useful for handling sudden spikes in transaction volume, such as a merchant onboarding batch or a real-time payment flow.
* **Sustained limits** govern how much throughput you can maintain continuously. Exceeding the sustained limit — even if each individual burst stays within burst limits — will trigger `429` responses.

A well-designed integration paces requests evenly rather than sending them all at once. Use a token-bucket or leaky-bucket approach in your application layer to smooth request rates before they reach the API.

## Maximizing Throughput with the Batch Endpoint

The single-VPA endpoint (`GET /v1/verify/upi`) counts as one request per call. If you need to screen many VPAs — for example during a nightly batch reconciliation or a bulk merchant onboarding — use the batch endpoint instead:

```
POST /v1/verify/upi/batch
```

The batch endpoint accepts up to **100 UPI VPAs per request** and counts as a single request against your rate limit quota, giving you up to 100× the effective throughput for bulk workloads.

### Batch Request Example

```bash theme={null}
curl --request POST \
  --url "https://api.fraudtraceai.com/v1/verify/upi/batch" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "vpas": [
      "user1@upi",
      "user2@upi",
      "user3@upi"
    ]
  }'
```

```python theme={null}
import requests

vpas = ["user1@upi", "user2@upi", "user3@upi"]

response = requests.post(
    "https://api.fraudtraceai.com/v1/verify/upi/batch",
    json={"vpas": vpas},
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
)

results = response.json()
```

<Tip>
  When processing thousands of VPAs, chunk your list into groups of 100 and send one batch request per chunk. This is far more efficient than issuing individual `GET /v1/verify/upi` calls and minimizes the chance of hitting rate limits.
</Tip>

## Requesting a Limit Increase

If your integration regularly approaches or exceeds its rate limit — for example, you're operating at scale or handling peak-time payment flows — contact the FraudTrace AI team to discuss a higher-throughput plan. Include the following information to speed up the review:

* Your current API key identifier (not the secret value)
* Your expected average and peak requests per minute
* A brief description of your use case

Reach out via the contact form at [fraudtraceai.com](https://fraudtraceai.com) or through your account manager if you have one.