Troubleshooting

This guide covers common issues and their solutions when integrating with Spamidate.

Authentication Issues

MISSING_API_KEY

Error: API key is required

Causes:

• No API key provided in the request
• API key sent with wrong header name

Solutions:

cURL

# Correct - X-API-Key header
curl -H "X-API-Key: spm_live_..." https://api.spamidate.com/validate

# Also correct - Authorization Bearer
curl -H "Authorization: Bearer spm_live_..." https://api.spamidate.com/validate

JavaScript

// Correct
const response = await fetch('https://api.spamidate.com/validate', {
  headers: {
    'X-API-Key': process.env.SPAMIDATE_API_KEY,
  },
});

// Verify the environment variable is set
if (!process.env.SPAMIDATE_API_KEY) {
  throw new Error('SPAMIDATE_API_KEY is not set');
}

---

INVALID_API_KEY

Error: Invalid API key

Causes:

• API key is malformed
• API key was deleted
• Using wrong environment’s key

Solutions:

1. Verify key format: API keys start with spm_live_ or spm_test_
2. Check key length: Keys are 32+ characters
3. Regenerate if needed: Create a new key in your dashboard
4. Environment check: Ensure you’re using the correct key for your environment

// Validate key format before use
const apiKey = process.env.SPAMIDATE_API_KEY;
if (!apiKey?.startsWith('spm_')) {
  throw new Error('Invalid API key format');
}

---

API_KEY_DISABLED

Error: This API key has been disabled

Solutions:

1. Go to your dashboard
2. Navigate to API Keys
3. Re-enable the key or create a new one

---

Rate Limiting Issues

RATE_LIMIT_EXCEEDED

Error: Rate limit exceeded. 100 requests per minute allowed.

Solutions:

import { RateLimitError } from '@spamidate/sdk';

try {
  const result = await client.validate(email);
} catch (error) {
  if (error instanceof RateLimitError) {
    // Wait for the specified time
    await new Promise(r => setTimeout(r, error.retryAfter * 1000));
    // Retry
    return client.validate(email);
  }
}

Prevention:

• Use batch validation for multiple emails
• Implement request queuing
• Cache results to avoid re-validating

---

QUOTA_EXCEEDED

Error: Monthly quota exceeded

Solutions:

1. Check usage: GET /api/usage to see current consumption
2. Wait for reset: Quota resets at the start of your billing period
3. Upgrade plan: Increase your monthly quota

const usage = await client.getUsage();
console.log(`Used: ${usage.quota.used}/${usage.quota.limit}`);
console.log(`Resets: ${usage.period.daysRemaining} days`);

Tip

Growth tier and above include a 20% grace period buffer. You can use up to 120% of your quota before hard stop.

---

Validation Issues

Unexpected Low Scores

Problem: Emails you expect to be valid receive low scores.

Possible causes:

1. Domain issues:

   • Domain doesn’t have MX records
   • DNS is misconfigured
   • Recently created domain

2. Quality flags:

   • Catch-all domain (reduces score)
   • Role-based address (info@, support@)
   • Free email provider

Debug:

const result = await client.validate(email);

// Examine individual checks
for (const [check, data] of Object.entries(result.checks)) {
  if (!data.passed) {
    console.log(`${check}: ${data.reason}`);
  }
}

---

False Positives on Disposable Detection

Problem: Legitimate domain flagged as disposable.

Solutions:

1. Report false positive: Contact support with the domain
2. Check the check result:

const result = await client.validate(email);

if (result.checks.disposable?.passed === false) {
  // Review the metadata
  console.log(result.checks.disposable.metadata);
  console.log(result.checks.disposable.confidence);
}

Note

Disposable detection has a confidence score. Lower confidence may indicate edge cases.

---

Timeout Errors

Error: VALIDATION_TIMEOUT

Causes:

• Slow DNS resolution
• SMTP verification taking too long
• Network latency

Solutions:

1. Use quick mode:

const result = await client.validate(email, { quickMode: true });

2. Increase timeout (SDK):

const client = new Spamidate({
  apiKey: process.env.SPAMIDATE_API_KEY,
  timeout: 60000, // 60 seconds
});

---

Integration Issues

CORS Errors

Problem: Browser blocks requests with CORS error.

Solution: The API supports CORS, but you should validate server-side for security.

// Create a server endpoint
app.post('/api/validate-email', async (req, res) => {
  const client = new Spamidate({ apiKey: process.env.SPAMIDATE_API_KEY });
  const result = await client.validate(req.body.email);
  res.json(result);
});

---

SDK Not Installed

Error: Cannot find module '@spamidate/sdk'

Solutions:

# Ensure SDK is installed
npm install @spamidate/sdk

# Check package.json
cat package.json | grep spamidate

---

Environment Variable Not Set

Problem: API key is undefined at runtime.

Debug checklist:

1. Local development:

   # .env file
   SPAMIDATE_API_KEY=spm_live_...
   
   # Load with dotenv
   npm install dotenv

   require('dotenv').config();

2. Production deployment:

   • Verify environment variables are set in your hosting platform
   • Check variable names match exactly (case-sensitive)

---

Webhook Issues

Webhooks Not Received

Checklist:

1. URL is HTTPS: Webhooks require HTTPS endpoints
2. Endpoint is accessible: No firewall blocking requests
3. Returns 2xx status: Must respond within 30 seconds
4. Check webhook logs: View delivery status in dashboard

---

Signature Verification Fails

Causes:

• Wrong signing secret
• Body was modified before verification
• Timestamp mismatch

Solution:

// Use raw body, not parsed JSON
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-spamidate-signature'];
  const timestamp = req.headers['x-spamidate-timestamp'];

  // req.body is the raw Buffer
  const isValid = verifyWebhook(req.body.toString(), signature, timestamp, secret);
});

---

Performance Issues

Slow Validation Response

Solutions:

1. Use quick mode for real-time validation:

await client.validate(email, { quickMode: true });

2. Use batch validation for multiple emails:

// 1 request for 100 emails
await client.validateBatch(emails);

3. Cache results to avoid re-validating:

const cache = new Map();

async function validate(email) {
  const cached = cache.get(email);
  if (cached) return cached;

  const result = await client.validate(email);
  cache.set(email, result);
  return result;
}

---

High Error Rate

Debug steps:

1. Check recent errors:

const usage = await client.getUsage();
console.log(usage.recentErrors);

2. Common causes:
   • unauthorized: API key issues
   • rateLimited: Too many requests
   • badRequest: Invalid email formats
   • serverError: Temporary API issues

---

Getting Help

Information to Include

When contacting support, include:

1. Request ID: From X-Request-Id response header
2. Timestamp: When the issue occurred
3. Error code and message: Full error response
4. Email(s) tested: (if not sensitive)
5. Code snippet: How you’re making the request

Support Channels

• Documentation: docs.spamidate.com
• Dashboard: Check status and logs
• Email: support@spamidate.com

Status Page

Check for known issues: status.spamidate.com