Skip to main content
Huntr returns JSON error bodies with an error string. Some responses include structured fields for programmatic handling.

​
Common status codes

StatusMeaning
400Invalid request — bad JSON, missing fields, invalid filters
401Missing or invalid x-api-key
402Insufficient credits — top up and retry
422Bulk workflow should use list/enrichment endpoints (BULK_ENRICHMENT_REQUIRED)
429Rate limit exceeded — retry after reset
500Server or upstream failure — credits refunded on failed enrichment/research where applicable

​
Standard error shape

{
  "error": "Human-readable message"
}

​
Query validation (search endpoints)

Company and person search return detailed validation errors for bad filters: 
{
  "error": "Invalid industry value",
  "field": "query.industry",
  "invalid_values": ["SaaS"],
  "accepted_values": ["Software Development", "..."]
}
Use accepted_values to fix enum fields like industry, type, and headcount growth timespan.

​
Bulk enrichment rejection

When /research cannot run a multi-entity enrichment workflow within budget: 
{
  "success": false,
  "code": "BULK_ENRICHMENT_REQUIRED",
  "message": "This request discovers multiple entities and performs paid enrichment for each...",
  "request_id": "req_...",
  "price": 0,
  "credits_used": 0,
  "recommended_workflow": [
    { "endpoint": "/company-search", "purpose": "Build a company list" },
    { "endpoint": "/person-search", "purpose": "Find relevant people" },
    { "endpoint": "/person-email", "purpose": "Find an email for each selected person" }
  ]
}
Not charged. Follow recommended_workflow.

​
Research failures

Failed research runs return price: 0. Async failures include error and optional error_code on the status endpoint.

​
Next step