Handling Errors

​

Error Response Format

{
  "error": "Error Type",
  "message": "Detailed error message"
}

{
  "detail": "Error description"
}

​

HTTP Status Codes

​

Common Error Types

​

400 Bad Request

• Missing required fields in request body
• Invalid field types or formats
• Malformed JSON payload
• Empty or invalid lead/company data

{
  "error": "Bad Request",
  "message": "Invalid company data"
}

{
  "detail": "Lead data is required"
}

{
  "error": "Bad Request",
  "message": "Missing required field: qualification_criteria"
}

• Verify all required fields are included in your request
• Check that field types match the API specification
• Ensure JSON is properly formatted
• Validate input data before making the request

​

401 Unauthorized

• Missing x-api-key header
• Invalid or expired API key
• API key not properly formatted

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

• Verify your API key is correct
• Ensure the x-api-key header is included in every request
• Check that your API key hasn’t been revoked or expired
• Get a new API key from the dashboard

​

429 Rate Limit Exceeded

• Exceeded the rate limit of 500 requests per minute

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}

• Implement exponential backoff and retry logic
• Wait 60 seconds before retrying
• Spread requests over time to stay under the limit
• Use async endpoints for bulk operations
• Contact support if you need a higher rate limit

​

500 Internal Server Error

• Temporary server issue
• Unexpected error during processing
• Service degradation

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

• Wait a few seconds and retry the request
• Implement retry logic with exponential backoff
• If the error persists, contact support at [email protected]

​

Rate Limits

• 500 requests per minute per API key

• X-RateLimit-Limit: Maximum requests allowed per minute
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets

​

Best Practices for Rate Limiting

1. Implement Retry Logic

import requests
import time

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

            if response.status_code == 429:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limit exceeded. Waiting {wait_time} seconds...")
                time.sleep(wait_time)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

2. Use Async Endpoints for Bulk Operations

3. Implement Request Queuing

​

Timeout Issues

​

Long-Running Requests

• Enrich Lead: P95 runtime ~5 minutes, up to 10 minutes
• Enrich Company: Several minutes depending on research depth
• QA Agent: Varies based on criteria complexity

1. Set Appropriate Timeouts

import requests

# For sync endpoints, set timeout to at least 15 minutes (900 seconds)
response = requests.post(
    "https://api.sixtyfour.ai/enrich-lead",
    headers=headers,
    json=data,
    timeout=900  # 15 minutes
)
response.raise_for_status()

2. Use Async Endpoints

import requests
import time

# Start async job
response = requests.post(
    "https://api.sixtyfour.ai/enrich-lead-async",
    headers=headers,
    json=data
)
response.raise_for_status()
task_id = response.json()["task_id"]

# Poll for results
while True:
    status_response = requests.get(
        f"https://api.sixtyfour.ai/job-status/{task_id}",
        headers=headers
    )
    status_response.raise_for_status()
    status = status_response.json()

    if status["status"] == "completed":
        results = status["result"]
        break
    elif status["status"] == "failed":
        print(f"Job failed: {status.get('error')}")
        break

    time.sleep(10)

3. Use Webhooks

​

Common Troubleshooting Scenarios

​

Issue: “Invalid API key” error

• Is the x-api-key header included?
• Is the API key copied correctly (no extra spaces)?
• Has the API key been revoked or expired?

​

Issue: Request times out

• Are you using a sync endpoint for long-running operations?
• Is your HTTP client timeout set appropriately?

​

Issue: Empty or incomplete results

• Did you provide enough input data for the enrichment?
• Is the struct field properly defined with clear descriptions?
• Are you requesting data that may not be publicly available?

• Provide as much input data as possible (name, company, LinkedIn, etc.)
• Write clear, detailed descriptions in the struct field
• Check the confidence_score in the response to gauge data quality

​

Issue: Rate limit exceeded frequently

• Are you making more than 500 requests per minute?
• Are you implementing retry logic properly?

• Use async endpoints for bulk operations
• Implement request queuing to control the rate
• Add delays between requests
• Contact support if you need a higher limit

​

Issue: “Bad Request” with valid data

• Is the JSON properly formatted?
• Are all required fields included?
• Are field types correct (object vs string, etc.)?

​

Getting Help

1. Check the API Reference for endpoint-specific requirements
2. Review the starter notebooks for working examples
3. Contact support at [email protected]
4. Include the following in your support request:
   • Request/response details (remove sensitive data)
   • Error message
   • Endpoint being called
   • Approximate timestamp of the error