Skip to main content

​
Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

​
Error Codes

​
Authentication Errors

CodeHTTP StatusDescription
INVALID_API_KEY401API key is missing, invalid, malformed, or disabled

​
Credit & Limit Errors

CodeHTTP StatusDescription
MONTHLY_LIMIT_EXCEEDED402Monthly credit limit exceeded. Please contact administrator.
INSUFFICIENT_CREDITS500Insufficient credits to complete this request. Please contact administrator.

​
Validation Errors

CodeHTTP StatusDescription
DOMAIN_REQUIRED400Domain is required
INVALID_DOMAIN_FORMAT400Invalid domain format. Expected: example.com
INVALID_REQUEST400Validation failed (varies by context)
INVALID_WEBHOOK_URL400Webhook URL validation failed (see details below)
VALIDATION_ERROR400Validation failed

​
Webhook URL Validation Messages

The INVALID_WEBHOOK_URL error may return one of these messages:
  • Invalid URL format
  • Webhook URL must use HTTPS
  • Localhost URLs are not allowed
  • Webhook URL resolves to a private IP address
  • Webhook URL is a private IP address

​
Access Errors

CodeHTTP StatusDescription
SOURCE_ACCESS_DENIED403Access denied to sources: [list]
ACCESS_DENIED403You do not have access to this job

​
Job Errors

CodeHTTP StatusDescription
COMPANY_NOT_FOUND500We could not find a company for this domain. Please verify the domain.
INTERNAL_ERROR500Something went wrong. Please try again.

​
Handling Errors

const response = await fetch(url, options);
const data = await response.json();

if (!data.success) {
  switch (data.error.code) {
    case 'INVALID_API_KEY':
      throw new Error('Check your API key');
    case 'MONTHLY_LIMIT_EXCEEDED':
      throw new Error('Monthly credit limit exceeded');
    case 'INSUFFICIENT_CREDITS':
      throw new Error('Not enough credits');
    case 'DOMAIN_REQUIRED':
    case 'INVALID_DOMAIN_FORMAT':
      throw new Error('Invalid domain');
    default:
      throw new Error(data.error.message);
  }
}