FraudTrace AI API Error Codes and Troubleshooting Guide

When a request to the FraudTrace AI API cannot be completed successfully, the API returns an HTTP error status code alongside a JSON body that describes what went wrong. Understanding these codes and building appropriate error handling into your integration will make your application more resilient and easier to debug in production.

Error Response Format

Every error response uses the same JSON structure regardless of the status code. The error field contains a machine-readable code you can use for programmatic handling, while message provides a human-readable explanation.

{
  "error": "unauthorized",
  "message": "API key is missing or invalid."
}

Always check the error field — not just the HTTP status code — when building error-handling logic. The error value is stable and versioned; the message text may change over time.

Error Code Reference

The table below covers every error code the API can return, what triggers it, and how to resolve it.

HTTP Status	Error Code	Description	Resolution
`400`	`bad_request`	Missing or invalid request parameters	Check that all required query parameters and body fields are present and correctly formatted
`401`	`unauthorized`	API key is missing or invalid	Verify your `Authorization: Bearer` token is correct and has not been rotated
`404`	`not_found`	Endpoint or resource not found	Check the URL path for typos; confirm the resource ID exists
`422`	`validation_error`	Request body failed schema validation	Review the `message` field for specifics and correct your request body
`429`	`rate_limit_exceeded`	Too many requests sent in the current window	Implement exponential backoff and retry after the period indicated by `Retry-After`
`500`	`internal_error`	Unexpected server-side error	Retry with backoff; contact support if the error persists
`503`	`service_unavailable`	Service is temporarily unavailable	Retry with exponential backoff; check the FraudTrace status page

Common Error Examples

401 Unauthorized

Returned when the Authorization header is missing, malformed, or contains an invalid API key.

{
  "error": "unauthorized",
  "message": "API key is missing or invalid."
}

Common causes:

The Authorization header is missing entirely.
The token is prefixed incorrectly (e.g. Token or Basic instead of Bearer).
The API key has been rotated or revoked in the dashboard.

400 Bad Request

Returned when a required parameter is absent or a parameter value is in the wrong format.

{
  "error": "bad_request",
  "message": "The 'upi' query parameter is required."
}

Common causes:

The upi query parameter is missing from a GET /v1/verify/upi request.
A UPI VPA is not in valid handle@provider format.
A batch request body is missing the vpas array.

429 Rate Limit Exceeded

Returned when you send more requests than your plan’s rate limit allows within a given window.

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

The response also includes a Retry-After header (in seconds) that tells you exactly how long to wait before sending the next request. See Rate Limits for the full breakdown of headers and handling guidance.

Do not immediately retry a 429 response. Hammering the API after a rate-limit error will not accelerate recovery and may extend your backoff window.

Retry Strategy

Different error codes call for different retry behaviors. The wrong strategy — such as retrying a 400 — wastes quota and delays diagnosis.

When to Retry

Status Code	Retry?	Strategy
`400`	❌ No	Fix the request before retrying
`401`	❌ No	Verify your API key
`404`	❌ No	Fix the URL or resource ID
`422`	❌ No	Fix the request body
`429`	✅ Yes	Exponential backoff — read `Retry-After`
`500`	✅ Yes	Retry up to 3 times with backoff
`503`	✅ Yes	Retry up to 3 times with exponential backoff

Exponential Backoff Rules

429: Start at 1 second, double on each attempt, cap at 32 seconds. Add random jitter (±0–500 ms) to prevent thundering-herd effects when multiple clients hit the limit simultaneously.
500 / 503: Retry up to 3 times using the same doubling pattern (1s → 2s → 4s).
4xx (except 429): Do not retry. The request is semantically invalid — retrying will produce the same error.

Python Retry Example

The example below shows two approaches: a simple manual loop and a cleaner implementation using the tenacity library.

import time
import requests

def verify_upi(vpa: str, api_key: str, max_retries: int = 4) -> dict:
    base_delay = 1  # seconds
    max_delay = 32

    for attempt in range(max_retries):
        response = requests.get(
            "https://api.fraudtraceai.com/v1/verify/upi",
            params={"upi": vpa},
            headers={"Authorization": f"Bearer {api_key}"},
        )

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", base_delay * (2 ** attempt)))
            wait = min(retry_after, max_delay)
            print(f"Rate limited. Retrying in {wait}s (attempt {attempt + 1}/{max_retries})")
            time.sleep(wait)
            continue

        if response.status_code in (500, 503):
            if attempt < max_retries - 1:
                wait = min(base_delay * (2 ** attempt), max_delay)
                print(f"Server error {response.status_code}. Retrying in {wait}s")
                time.sleep(wait)
                continue

        # For 4xx errors (except 429 already handled), raise immediately — do not retry
        response.raise_for_status()
        return response.json()

    raise Exception(f"Request failed after {max_retries} attempts")

import requests
from tenacity import (
    retry,
    stop_after_attempt,
    wait_exponential,
    retry_if_exception,
    before_sleep_log,
)
import logging

logger = logging.getLogger(__name__)

def _is_retryable(exc: Exception) -> bool:
    if isinstance(exc, requests.HTTPError):
        return exc.response.status_code in (429, 500, 503)
    return False

@retry(
    retry=retry_if_exception(_is_retryable),
    wait=wait_exponential(multiplier=1, min=1, max=32),
    stop=stop_after_attempt(4),
    before_sleep=before_sleep_log(logger, logging.WARNING),
)
def verify_upi(vpa: str, api_key: str) -> dict:
    response = requests.get(
        "https://api.fraudtraceai.com/v1/verify/upi",
        params={"upi": vpa},
        headers={"Authorization": f"Bearer {api_key}"},
    )
    response.raise_for_status()
    return response.json()

If you are processing large volumes of VPAs, use the batch endpoint (POST /v1/verify/upi/batch) to verify up to 100 VPAs in a single request. This reduces the total number of API calls and makes rate limit management much simpler.

Getting Help

If you consistently receive 500 errors that do not resolve after retrying, or if you believe an error is caused by a platform issue rather than a request problem, contact the FraudTrace AI support team with the full response body and the timestamp of the failing request. Including the X-Request-Id response header (if present) will significantly speed up diagnosis.

Overview

MuleTrace

CyberTrace

Mobile Trace

FraudTrace AI API Error Codes and Troubleshooting Guide

Error Response Format

Error Code Reference

Common Error Examples

401 Unauthorized

400 Bad Request

429 Rate Limit Exceeded

Retry Strategy

When to Retry

Exponential Backoff Rules

Python Retry Example

Getting Help

​Error Response Format

​Error Code Reference

​Common Error Examples

​401 Unauthorized

​400 Bad Request

​429 Rate Limit Exceeded

​Retry Strategy

​When to Retry

​Exponential Backoff Rules

​Python Retry Example

​Getting Help

Error Response Format

Error Code Reference

Common Error Examples

401 Unauthorized

400 Bad Request

429 Rate Limit Exceeded

Retry Strategy

When to Retry

Exponential Backoff Rules

Python Retry Example

Getting Help