Handling Errors

Documentation Index

Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Error Response Format

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

{
  "detail": "Error description"
}

{
  "detail": [
    {
      "loc": ["body", "workflow_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​

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
• Sending webhook_payload to /workflows/run for a workflow whose source block is not webhook
• Sending webhook_payload with JWT (dashboard session) auth instead of an API key
• Triggering a workflow whose source block is read_csv (not API-triggerable; switch to a webhook source block)
• webhook_payload is missing required columns from the webhook block’s input_schema, or is malformed JSON

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

{
  "error": "Bad Request",
  "message": "Invalid lead 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
• For workflow runs, ensure the workflow’s source block is webhook and that you’re authenticating with an API key — see Incoming Webhooks

​

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

​

403 Forbidden

• Requesting a feature that is not enabled for your organization (e.g., tier: "high" enrichment)

{
  "detail": "High tier company enrichment is not enabled for this org. Contact sales to request access."
}

{
  "detail": "High tier lead enrichment is not enabled for this org. Contact sales to request access."
}

• Verify your organization has access to the requested feature
• Contact sales to request access to restricted tiers
• Use a lower tier ("low" or "medium") if high-tier access is not available

​

404 Not Found (Workflows)

• Workflow ID does not exist or was deleted
• Run/job ID does not exist or is invalid
• Resource does not belong to your organization

{
  "detail": "Workflow not found"
}

• Verify the workflow ID using GET /workflows
• Verify the job_id from your run response
• Ensure you’re accessing resources created by your organization

​

422 Validation Error (Workflows)

• Invalid workflow definition (empty blocks, incompatible block types)
• Missing required fields in create/update requests
• Invalid block or edge configuration

{
  "detail": [
    {
      "loc": ["body", "workflow_definition", "blocks"],
      "msg": "blocks cannot be empty",
      "type": "value_error"
    }
  ]
}

• Ensure workflow has at least one block and valid edges
• Check block compatibility (e.g., webhook → company_enrichment)
• Use the workflow editor’s “Workflow API Reference” for block specs

​

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 support@sixtyfour.ai

​

Rate Limits

• 500 requests per minute per API key
• 5 concurrent deep searches per organization

• 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 or Workflows for Bulk Operations

3. Implement Request Queuing

​

Timeout Issues

​

Long-Running Requests

• People Intelligence: P95 runtime ~5 minutes, up to 10 minutes
• Company Intelligence: 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/people-intelligence",
    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/people-intelligence-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"] in ("failed", "cancelled"):
        print(f"Job {status['status']}: {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.)?

​

Issue: Workflow run stuck or not progressing

• Are you polling GET /workflows/runs/{run_id}/live_status?
• Is the overall_status still queued or running?
• Has the workflow been running for an unusually long time?

• Poll every 5-10 seconds; workflow runs can take several minutes
• Use overall_progress_percentage and blocks to see per-block progress
• To stop a run: POST /workflows/cancel?job_id={job_id}
• If a run appears stuck, check error_message in block status; consider cancelling and retrying

​

Issue: Webhook signature verification fails or deliveries stop

• Is your verifier using the raw request body bytes, not a re-serialized JSON parse?
• During rotation, does it iterate every v1= segment (not only the last)?
• Is your server clock within 5 minutes of UTC?
• Are you using the plaintext secret (sk_whsec_<64 hex>), not the masked preview shown in the dashboard?

• Log the raw body, the Sixtyfour-Signature header, and the HMAC your server computes; compare against what we sent.
• See Signing Secrets & Verification for the verification algorithm and reference code.
• If deliveries stop entirely, we may be refusing to deliver unsigned when signing is configured (fail-closed by design). Results remain available via /job-status/{task_id}.

​

Getting Help

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