> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhuntr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status codes and error shapes returned by the Huntr API.

Huntr returns JSON error bodies with an `error` string. Some responses include structured fields for programmatic handling.

## Common status codes

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

## Standard error shape

```json theme={null}
{
  "error": "Human-readable message"
}
```

## Query validation (search endpoints)

Company and person search return detailed validation errors for bad filters:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

* [Rate limits](/reference/rate-limits)
* [Choose your workflow](/concepts/choose-your-workflow)
* [API Reference](/api-reference)