Enrich Engine

Error Response Format

All API errors return a consistent JSON format:

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    // Additional context (optional)
  }
}

Status	Description
200	Success
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions or scope
404	Not Found - Resource does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Code	Description	Resolution
INVALID_API_KEY	API key is invalid or expired	Check key in Settings > API Keys
INSUFFICIENT_SCOPE	API key lacks required scope	Create new key with needed scopes
NO_ACTIVE_ORGANIZATION	No organization selected	Select an organization in dashboard
INSUFFICIENT_CREDITS	Not enough credits for operation	Purchase more credits
RATE_LIMIT_EXCEEDED	Too many requests	Wait and retry with backoff
INVALID_CSV_FORMAT	CSV file has invalid columns	Check required columns for workflow
RESOURCE_NOT_FOUND	Requested item doesn't exist	Verify ID is correct

Code	Description	Resolution
JOB_NOT_FOUND	Verification job doesn't exist	Check the job ID is correct
INVALID_JOB_STAGE	Job is not in the expected stage	Wait for job to reach awaiting_decision stage
NO_EMAILS_TO_VERIFY	List has no leads with email addresses	Enrich leads with emails first

API requests are rate limited to ensure fair usage. Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1706054400

When you exceed the rate limit, you'll receive a 429 response. Implement exponential backoff in your client to handle this gracefully.