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

# Error Codes

> Reference for all Huntd API error codes

## Error Response Format

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}
```

## Error Codes

### Authentication Errors

| Code              | HTTP Status | Description                                         |
| ----------------- | ----------- | --------------------------------------------------- |
| `INVALID_API_KEY` | 401         | API key is missing, invalid, malformed, or disabled |

### Credit & Limit Errors

| Code                     | HTTP Status | Description                                                                  |
| ------------------------ | ----------- | ---------------------------------------------------------------------------- |
| `MONTHLY_LIMIT_EXCEEDED` | 402         | Monthly credit limit exceeded. Please contact administrator.                 |
| `INSUFFICIENT_CREDITS`   | 500         | Insufficient credits to complete this request. Please contact administrator. |

### Validation Errors

| Code                    | HTTP Status | Description                                       |
| ----------------------- | ----------- | ------------------------------------------------- |
| `DOMAIN_REQUIRED`       | 400         | Domain is required                                |
| `INVALID_DOMAIN_FORMAT` | 400         | Invalid domain format. Expected: example.com      |
| `INVALID_REQUEST`       | 400         | Validation failed (varies by context)             |
| `INVALID_WEBHOOK_URL`   | 400         | Webhook URL validation failed (see details below) |
| `VALIDATION_ERROR`      | 400         | Validation 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

| Code                   | HTTP Status | Description                        |
| ---------------------- | ----------- | ---------------------------------- |
| `SOURCE_ACCESS_DENIED` | 403         | Access denied to sources: \[list]  |
| `ACCESS_DENIED`        | 403         | You do not have access to this job |

### Job Errors

| Code                | HTTP Status | Description                                                            |
| ------------------- | ----------- | ---------------------------------------------------------------------- |
| `COMPANY_NOT_FOUND` | 500         | We could not find a company for this domain. Please verify the domain. |
| `INTERNAL_ERROR`    | 500         | Something went wrong. Please try again.                                |

## Handling Errors

```javascript theme={null}
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);
  }
}
```