Error Handling

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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:

{
  "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:

Common Error Scenarios

1. Authentication Errors (401)

Problem: Missing or invalid API key

{
  "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

{
  "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

{
  "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 for parameter requirements

Problem: Invalid parameter values

{
  "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

{
  "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

{
  "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:

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:

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 for parameter specifications
3. Consult the Authentication and 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...)