# Error Handling

The HG Insights API uses standard HTTP status codes and provides detailed error messages to help you diagnose and resolve issues quickly.

## Error Response Structure

All error responses follow a consistent JSON structure:


```json
{
  "errors": [
    {
      "title": "Invalid request",
      "detail": "The request is invalid",
      "source": {
        "pointer": "/data/attributes/field-name"
      }
    }
  ]
}
```

Each error object contains:

- **title**: A short, human-readable summary of the problem
- **detail**: A detailed explanation of the error
- **source**: (Optional) The location in the request that caused the error


## HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

| Code | Description | What It Means |
|  --- | --- | --- |
| 200 | OK | Request was successful |
| 400 | Bad Request | The request body is malformed or contains invalid parameters |
| 401 | Unauthorized | Missing or invalid API key, or access denied to requested field groups |
| 404 | Not Found | The requested resource was not found |
| 422 | Unprocessable Entity | Request validation failed (missing or invalid parameters) |
| 500 | Internal Server Error | An unexpected error occurred on the server |


## Common Error Scenarios

### 1. Authentication Errors (401)

**Problem**: Missing or invalid API key


```json
{
  "errors": [{
    "title": "Unauthorized",
    "detail": "Invalid or missing API key"
  }]
}
```

**Solution**:

- Verify your API key is correct
- Ensure you're using the `Authorization: Bearer YOUR_API_KEY` header format
- Check that your API key starts with `hg_v2_`


**Problem**: Access denied to field groups


```json
{
  "errors": [{
    "title": "Unauthorized",
    "detail": "Access denied to field group: technographics"
  }]
}
```

**Solution**:

- Contact us at platform@hginsights.com to upgrade your field group entitlements
- Remove the restricted field group from your request


### 2. Validation Errors (400, 422)

**Problem**: Missing required parameters


```json
{
  "errors": [{
    "title": "Validation failed",
    "detail": "companies.ids is required",
    "source": {
      "pointer": "/companies/ids"
    }
  }]
}
```

**Solution**:

- Check the `source.pointer` to identify the problematic field
- Ensure all required parameters are included in your request
- Refer to the [API Reference](/v2/openapi) for parameter requirements


**Problem**: Invalid parameter values


```json
{
  "errors": [{
    "title": "Validation failed",
    "detail": "companies.ids exceeds maximum of 50 items",
    "source": {
      "pointer": "/companies/ids"
    }
  }]
}
```

**Solution**:

- Review parameter constraints (e.g., max array length, valid values)
- Split large requests into multiple batches if needed


### 3. Not Found Errors (404)

**Problem**: Invalid endpoint or company not found


```json
{
  "errors": [{
    "title": "Not found",
    "detail": "Company with ID ABC123 not found"
  }]
}
```

**Solution**:

- Verify the endpoint URL is correct
- Check that company IDs or domains are valid
- Some companies may not be in our database


### 4. Server Errors (500)

**Problem**: Unexpected server error


```json
{
  "errors": [{
    "title": "Internal Server Error",
    "detail": "An unexpected error occurred"
  }]
}
```

**Solution**:

- Retry the request after a short delay
- If the error persists, contact HG Insights support with the request details


## Best Practices

### 1. Implement Retry Logic

For transient errors (like 500 server errors), implement exponential backoff:


```python
import time
import requests

def make_request_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)

        if response.status_code == 200:
            return response.json()

        if response.status_code >= 500:
            # Server error - retry with exponential backoff
            wait_time = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait_time)
            continue

        # Client error - don't retry
        response.raise_for_status()

    raise Exception("Max retries exceeded")
```

### 2. Log Error Details

Always log the full error response for debugging:


```javascript
try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestData)
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error('API Error:', {
      status: response.status,
      errors: errorData.errors
    });
    throw new Error(`API request failed: ${response.status}`);
  }

  return await response.json();
} catch (error) {
  console.error('Request failed:', error);
  throw error;
}
```

## Troubleshooting Checklist

If you're experiencing errors, check:

- ✅ API key is valid and properly formatted
- ✅ Authorization header is included: `Authorization: Bearer YOUR_API_KEY`
- ✅ Request body is valid JSON
- ✅ All required parameters are included
- ✅ Parameter values meet validation requirements
- ✅ Field groups requested are included in your subscription
- ✅ Base URL is correct: `https://api.hginsights.com/data-api/v2`
- ✅ Content-Type header is set: `Content-Type: application/json`


## Getting Help

If you continue experiencing errors:

1. Check the error message and `source.pointer` for specific guidance
2. Review the [API Reference](/v2/openapi) for parameter specifications
3. Consult the [Authentication](/v2/guides/authentication) and [Enrichment](/v2/guides/enrichment) guides
4. Contact us at platform@hginsights.com for support


Include the following information when reporting issues:

- Full error response
- Request details (URL, headers, body)
- Timestamp of the error
- Your API key prefix (e.g., `hg_v2_abc...`)