Error Codes

Learn about error responses and how to handle them properly in your application.

Error Response Format

All error responses follow this standard format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Status Code	Meaning	When It Occurs
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid input (missing parameter, bad format)
`401`	Unauthorized	Invalid or missing API key
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error on our end

Common Errors

Missing Query Parameter

400 Bad Request

{
  "success": false,
  "error": "Missing required parameter: 'q'"
}

Cause: The q parameter is required but was not provided.

Solution: Always include ?q=email@example.com in your request URL.

Invalid Email Format

400 Bad Request

{
  "success": false,
  "error": "Invalid email format"
}

Cause: The provided email doesn't match basic email format requirements.

Solution: Validate email format before sending to the API.

Invalid Domain Format

400 Bad Request

{
  "success": false,
  "error": "Invalid domain format. Domain must include a TLD (e.g., example.com)",
  "domain": "invalid"
}

Cause: Domain doesn't have a valid TLD or format.

Solution: Ensure domains include a TLD (e.g., .com, .org).

Invalid or Missing API Key

401 Unauthorized

{
  "success": false,
  "error": "Invalid or missing API key"
}

Cause: API key is missing, expired, disabled, or invalid.

Solutions:

Verify your API key is correct and starts with sk_
Check that the key is active in your account settings
Ensure the Authorization header format is correct: Bearer YOUR_KEY
Regenerate the key if it's been compromised

Rate Limit Exceeded

429 Too Many Requests

{
  "success": false,
  "error": "Rate limit exceeded"
}

Cause: You've exceeded your plan's rate limit.

Solutions:

Implement exponential backoff and retry logic
Cache results to reduce API calls
Upgrade your plan for higher limits

Internal Server Error

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error"
}

Cause: Something went wrong on our servers.

Solutions:

Retry the request with exponential backoff
If the issue persists, contact support
Implement "fail open" logic to allow signups during outages

Error Handling Best Practices

Fail Open Strategy

Always implement "fail open" logic: if the API is unavailable or returns an error, allow the signup to proceed rather than blocking legitimate users.

Fail Open Example

async function checkEmail(email) {
  try {
    const response = await fetch(`/api/check?q=${email}`);
    
    // If API fails, allow signup (fail open)
    if (!response.ok) {
      console.error('API error:', response.status);
      return { isDisposable: false }; // Allow signup
    }
    
    const data = await response.json();
    return {
      isDisposable: data.data?.risk_level === 'high'
    };
  } catch (error) {
    // On any error, allow signup
    console.error('Email check failed:', error);
    return { isDisposable: false };
  }
}

Retry Logic with Exponential Backoff

Retry with Backoff

async function checkEmailWithRetry(email, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(`/api/check?q=${email}`, {
        timeout: 5000
      });
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry on 4xx errors (client errors)
      if (response.status >= 400 && response.status < 500) {
        return null;
      }
      
      // Retry on 5xx errors with exponential backoff
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    } catch (error) {
      if (attempt === maxRetries) {
        console.error('All retries failed:', error);
        return null; // Fail open
      }
    }
  }
  
  return null;
}

Logging and Monitoring

Always log API errors for monitoring and debugging:

async function checkEmail(email) {
  try {
    const response = await fetch(`/api/check?q=${email}`);
    
    if (!response.ok) {
      // Log error with context
      logger.error('PureSignup API error', {
        status: response.status,
        email: email, // Be careful with PII
        timestamp: new Date().toISOString()
      });
      
      return { isDisposable: false };
    }
    
    return await response.json();
  } catch (error) {
    logger.error('PureSignup request failed', {
      error: error.message,
      email: email,
      timestamp: new Date().toISOString()
    });
    
    return { isDisposable: false };
  }
}

Need Help?

If you're experiencing persistent errors or need assistance, contact our support team.