Errors

Error responses and how to handle them

Errors

All error responses return a JSON object with a detail field containing a human-readable message.

{
  "detail": "Error message here"
}

Common errors

Authentication errors

Status	Message	Cause	Solution
401	`Invalid API key.`	API key is missing, malformed, or revoked	Check your API key in the dashboard

{"detail": "Invalid API key."}

Billing errors

Status	Message	Cause	Solution
402	`Insufficient credits — please top up your balance.`	Account has no remaining credits	Purchase more credits in the dashboard

{"detail": "Insufficient credits — please top up your balance."}

Rate limiting errors

Status	Message	Cause	Solution
403	`Your IP address is banned. Contact the service administrator to unlock access.`	Too many requests with `black` category results	Contact support to unban, or wait for automatic lift

{"detail": "Your IP address is banned. Contact the service administrator to unlock access."}

Note: Before an IP ban, responses include remaining_attempts_before_ban:

{
  "email": "test@disposable.com",
  "category": "black",
  "remaining_attempts_before_ban": 2
}

File upload errors

Status	Message	Cause	Solution
400	`Invalid file extension.`	File type not supported	Use CSV, XLSX, or TSV
413	`Storage quota exceeded, please delete old projects.`	Account storage limit reached	Delete old projects in dashboard

Task errors

Status	Message	Cause	Solution
404	`Task does not exist or has not started`	Invalid task ID	Check the task ID from your submit response
404	`Task is still processing`	Tried to download before completion	Wait for status to be `completed`
500	`Error checking task status: ...`	Internal processing error	Retry or contact support

Handling errors in code

Python

import requests

def check_email(email: str, api_key: str) -> dict:
    response = requests.post(
        "https://api.user.cleaning/v1/external-api-requests/check-email",
        params={"email": email},
        headers={"X-API-Key": api_key}
    )
    
    if response.status_code == 401:
        raise Exception("Invalid API key")
    elif response.status_code == 402:
        raise Exception("Insufficient credits")
    elif response.status_code == 403:
        raise Exception("IP address banned")
    elif not response.ok:
        raise Exception(f"API error: {response.json().get('detail', 'Unknown error')}")
    
    return response.json()

JavaScript

async function checkEmail(email, apiKey) {
  const response = await fetch(
    `https://api.user.cleaning/v1/external-api-requests/check-email?email=${encodeURIComponent(email)}`,
    {
      method: 'POST',
      headers: { 'X-API-Key': apiKey }
    }
  );
  
  if (response.status === 401) {
    throw new Error('Invalid API key');
  } else if (response.status === 402) {
    throw new Error('Insufficient credits');
  } else if (response.status === 403) {
    throw new Error('IP address banned');
  } else if (!response.ok) {
    const data = await response.json();
    throw new Error(data.detail || 'Unknown error');
  }
  
  return response.json();
}

PHP

function checkEmail(string $email, string $apiKey): array {
    $url = "https://api.user.cleaning/v1/external-api-requests/check-email?" . http_build_query(['email' => $email]);
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: $apiKey"]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $data = json_decode($response, true);
    
    if ($httpCode === 401) {
        throw new Exception('Invalid API key');
    } elseif ($httpCode === 402) {
        throw new Exception('Insufficient credits');
    } elseif ($httpCode === 403) {
        throw new Exception('IP address banned');
    } elseif ($httpCode >= 400) {
        throw new Exception($data['detail'] ?? 'Unknown error');
    }
    
    return $data;
}

Rate limit handling

To avoid IP bans, monitor the remaining_attempts_before_ban field:

def check_email_safe(email: str, api_key: str) -> dict:
    result = check_email(email, api_key)
    
    remaining = result.get("remaining_attempts_before_ban")
    if remaining is not None and remaining <= 2:
        # Log warning — approaching rate limit
        print(f"Warning: Only {remaining} attempts remaining before IP ban")
    
    return result

If you're validating user input in a public form, consider rate limiting on your end before calling the API.

Errors

On this page