FraudTrace AI API Rate Limits and Throughput Guidance

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.

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.

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/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:

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

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.

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.

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

HTTP/1.1 429 Too Many Requests
Retry-After: 14
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678

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.

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.

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

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"
    ]
  }'

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()

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.

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 or through your account manager if you have one.

Overview

MuleTrace

CyberTrace

Mobile Trace

FraudTrace AI API Rate Limits and Throughput Guidance

Rate Limit Tiers

Rate Limit Response Headers

Example Response Headers

When You Exceed the Limit

Handling 429 in Python

Burst vs. Sustained Throughput

Maximizing Throughput with the Batch Endpoint

Batch Request Example

Requesting a Limit Increase

​Rate Limit Tiers

​Rate Limit Response Headers

​Example Response Headers

​When You Exceed the Limit

​Handling 429 in Python

​Burst vs. Sustained Throughput

​Maximizing Throughput with the Batch Endpoint

​Batch Request Example

​Requesting a Limit Increase

Rate Limit Tiers

Rate Limit Response Headers

Example Response Headers

When You Exceed the Limit

Handling 429 in Python

Burst vs. Sustained Throughput

Maximizing Throughput with the Batch Endpoint

Batch Request Example

Requesting a Limit Increase