API rate limits and error handling: every status code explained

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-DailyLimit-Remaining: 9500

{
  "error": "Rate limit exceeded",
  "limit": 60,
  "window": "1 minute",
  "current": 61,
  "retry_after_seconds": 45
}

Retry-After: 45
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1747615245

{
  "error": "Daily limit exceeded",
  "limit": 10000,
  "current": 10001,
  "resets_at": "midnight UTC"
}

{
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer VEC..."
}

{
  "error": "Invalid or inactive API key"
}

{
  "error": "API key is suspended",
  "reason": "This API key has been suspended"
}

{
  "error": "Access denied",
  "reason": "IP address is blocked",
  "blocked_until": "2026-12-31T23:59:59Z"
}

{
  "error": "Insufficient credits",
  "current_balance": 0,
  "message": "Please purchase more credits to continue"
}

{
  "error": "Insufficient credits",
  "required": 5000,
  "current_balance": 1000,
  "message": "You need 5000 credits but only have 1000 available"
}

const API_KEY = process.env.VEC_API_KEY;
const BASE = 'https://app.validemailchecker.com/api';

async function verifyEmail(email) {
  const response = await fetch(`${BASE}/verify-single`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type':  'application/json',
    },
    body: JSON.stringify({ email }),
  });

  const data = await response.json();

  switch (response.status) {
    case 200: return data;
    case 400: throw new Error(`Bad request: ${data.error}`);
    case 401: throw new Error('Invalid API key — check your credentials');
    case 402: throw new Error(`Insufficient credits. Balance: ${data.current_balance}`);
    case 403:
      if (data.error.includes('suspended')) throw new Error('API key suspended');
      if (data.error.includes('blocked'))   throw new Error(`IP blocked until: ${data.blocked_until}`);
      throw new Error(`Access denied: ${data.error}`);
    case 429: {
      const retry = data.retry_after_seconds || 60;
      throw new Error(`Rate limited — retry after ${retry}s`);
    }
    case 500: throw new Error('Server error — please retry');
    default:  throw new Error(`Unexpected error: ${data.error}`);
  }
}

async function verifyWithRetry(email, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await verifyEmail(email);
    } catch (error) {
      if (error.message.includes('Rate limited')) {
        const waitMs = Math.pow(2, attempt) * 30_000; // 30s, 60s, 120s
        await new Promise(r => setTimeout(r, waitMs));
        continue;
      }
      if (error.message.includes('Server error') && attempt < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 5_000));
        continue;
      }
      throw error; // never retry 4xx auth/credit errors
    }
  }
  throw new Error('Max retries exceeded');
}

import os, time, requests

API_KEY = os.environ['VEC_API_KEY']
BASE = 'https://app.validemailchecker.com/api'

def verify_email(email):
    r = requests.post(
        f'{BASE}/verify-single',
        headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'},
        json={'email': email},
    )
    data = r.json()

    if r.status_code == 200: return data
    if r.status_code == 401: raise Exception('Invalid API key')
    if r.status_code == 402: raise Exception(f"Insufficient credits: {data.get('current_balance', 0)} remaining")
    if r.status_code == 403: raise Exception(f"Access denied: {data.get('error')}")
    if r.status_code == 429:
        raise Exception(f"Rate limited. Retry after {data.get('retry_after_seconds', 60)}s")
    raise Exception(f"API error: {data.get('error')}")


def verify_with_retry(email, max_retries=3):
    for attempt in range(max_retries):
        try:
            return verify_email(email)
        except Exception as e:
            if 'Rate limited' in str(e):
                time.sleep((2 ** attempt) * 30)
                continue
            raise
    raise Exception('Max retries exceeded')

async function makeRequest(endpoint, options) {
  const response = await fetch(`${BASE}${endpoint}`, options);

  const remaining       = parseInt(response.headers.get('X-RateLimit-Remaining')     || '60', 10);
  const dailyRemaining  = parseInt(response.headers.get('X-DailyLimit-Remaining')    || '10000', 10);

  if (remaining < 10) {
    console.warn(`Only ${remaining} requests left this minute — slowing down`);
    await new Promise(r => setTimeout(r, 1_000));
  }
  if (dailyRemaining < 100) {
    console.warn(`Only ${dailyRemaining} requests left today — escalate`);
  }

  return response;
}