Common Issues

I am getting 401 errors

A 401 Unauthorized response means the API could not authenticate your request. Common causes:

Missing API key. Make sure you include the Authorization header in every request.

# Correct
curl -H "Authorization: Bearer sv_live_abc123..."

# Wrong (missing header)
curl https://scamverify.ai/api/v1/phone/lookup

Wrong key format. ScamVerify™ API keys start with sv_live_ (production) or sv_test_ (test mode). Keys from other services (for example, keys starting with sk_ or pk_) will be rejected.

Revoked key. If you revoked the key in your dashboard, it can no longer be used. Create a new key at Settings > API.

Extra whitespace or line breaks. Make sure your key does not have trailing whitespace, newline characters, or quotes around it in your environment variable.

I am getting 429 errors

A 429 Too Many Requests response means you have exceeded your plan's rate limit (measured in requests per minute).

Check the Retry-After header. The response includes a Retry-After header telling you how many seconds to wait before retrying.

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  console.log(`Wait ${retryAfter} seconds before retrying`);
}

Rate limits by plan:

Solutions:

• Add retry logic with exponential backoff to your client
• Use batch endpoints instead of individual lookups to reduce request count
• Upgrade your plan for a higher RPM limit
• Cache results on your side to avoid redundant lookups

I am getting 402 errors

A 402 Payment Required response means your quota for the billing period is exhausted.

Check your current usage. Call the usage endpoint to see your remaining quota:

curl https://scamverify.ai/api/v1/usage \
  -H "Authorization: Bearer sv_live_abc123..."

Solutions:

• Upgrade to a higher plan for more monthly lookups
• Wait for your quota to reset at the start of the next billing cycle
• Cached lookups do not consume quota, so repeated lookups of the same target are free

My cached results are stale

ScamVerify™ caches lookup results for 24 hours by default. If you need fresh data, use the force_refresh parameter:

curl -X POST https://scamverify.ai/api/v1/phone/lookup \
  -H "Authorization: Bearer sv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12025551234", "force_refresh": true}'

Important: A forced refresh consumes quota even if the number was previously cached. Use this only when you specifically need updated data.

The cached field in the response tells you whether the result came from cache:

{
  "risk_score": 45,
  "verdict": "medium_risk",
  "cached": true
}

Batch request returns partial failures

Batch endpoints process each item independently. Some items may succeed while others fail. Check the error field on each result:

{
  "results": [
    {
      "phone_number": "+12025551234",
      "risk_score": 15,
      "verdict": "safe",
      "error": null
    },
    {
      "phone_number": "invalid",
      "risk_score": null,
      "verdict": null,
      "error": "Invalid phone number format"
    }
  ]
}

How to handle partial failures:

• Iterate through the results array and check each item for an error field
• Items with errors do not consume quota
• Retry failed items individually if the error is transient (such as a timeout)
• Do not retry items with validation errors (such as invalid format)

Phone number format not accepted

The API accepts US phone numbers in these formats:

Best practice: Normalize to E.164 format (+1 followed by 10 digits) before calling the API. This eliminates parsing ambiguity.

URL lookup returns low confidence

A low-confidence result means the domain has limited data across all threat intelligence sources. This typically happens with:

• Newly registered domains that have not yet appeared in threat feeds
• Obscure domains with very little traffic or reporting history
• Subdomains of otherwise clean parent domains

What to do:

• Do not treat low confidence as "safe." Treat it as "unknown."
• Check back later. As the domain ages and appears in more data sources, confidence will increase.
• Use force_refresh to get the latest data if you checked the domain previously.
• Combine the ScamVerify™ result with your own domain age checks or WHOIS data for additional context.

Email analysis missing header_analysis

The header_analysis field (containing SPF, DKIM, and DMARC results) only appears when you include the raw_headers parameter in your request.

Without headers (no header analysis):

curl -X POST https://scamverify.ai/api/v1/email/analyze \
  -H "Authorization: Bearer sv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"email_body": "Click here to verify your account..."}'

With headers (full analysis):

curl -X POST https://scamverify.ai/api/v1/email/analyze \
  -H "Authorization: Bearer sv_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_body": "Click here to verify your account...",
    "raw_headers": "From: noreply@example.com\nReceived-SPF: pass\nDKIM-Signature: v=1; a=rsa-sha256; d=example.com..."
  }'

Without raw headers, the API still analyzes the email body for phishing indicators, embedded URLs, and social engineering patterns. However, SPF/DKIM/DMARC validation (which catches spoofed senders) requires the raw headers.

My quota is not decrementing

Cached lookups are free. If you look up the same phone number, URL, text, or email within 24 hours, the API returns cached results without consuming quota. The cached: true field in the response confirms this.

Same-user re-lookups are free. If the same API key looks up the same target multiple times, only the first lookup counts against your quota.

To verify your current quota:

curl https://scamverify.ai/api/v1/usage \
  -H "Authorization: Bearer sv_live_abc123..."

The response shows your limits, usage, and remaining quota for each channel.

Still need help?

If your issue is not covered here, contact us through the ScamVerify™ contact form. Include your error response, the endpoint you are calling, and (if possible) a redacted version of your request.