Handling Errors

​

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 read_csv workflow without a valid specs_override.resource_handle_id from /storage/csv/upload, or with a handle_id that has expired or belongs to a different organization
• webhook_payload is missing required columns from the webhook block’s input_schema, or is malformed JSON
• Invalid search exclusions: sending exclude_public_ids in company mode (people-only) or alongside exclude_entity_ids, using a saved exclusion list whose entity type doesn’t match the search mode or that is not yet ready, or sending exclusions on a cursor request — see Search Exclusions
• Invalid monitor definitions: a frequency outside 1h–30d, a tier other than low, medium, or high, a subject_type other than company or lead, an empty struct, a column used as both a key column and a watched field, a row with no value in any key column, two rows with the same key values, or a non-public webhook_url — see Monitor Endpoints
• Invalid monitor uploads: a file that is not .csv, .json, .jsonl, or .ndjson, is larger than 100 MB, has no rows or more than 100,000 rows, or cannot be parsed; a config that is not valid JSON, contains an unknown field, has an empty or invalid webhook_event_types list, or names a key_columns entry missing from the file— see Create monitor from a file
• A cursor for GET /monitors/{monitor_id}/rows that did not come from a previous next_cursor — see List rows

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

{
  "detail": "Rows 0 and 3 have the same identity values (Acme Robotics, acmerobotics.com). Add a column that tells them apart, or remove the duplicate."
}

• 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, match the request body to the source block: webhook_payload for webhook workflows (Incoming Webhooks) or specs_override.resource_handle_id for read_csv workflows (Workflow Execution). webhook_payload requires API key or OAuth auth — JWT (dashboard session) is rejected.

​

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

​

402 Payment Required

• Your balance doesn’t cover the estimated cost of a bulk intelligence job (rows × per-row tier price)

• Add credits in the dashboard before resubmitting
• Reduce the row count or use a cheaper tier to lower the estimated cost

​

403 Forbidden

• Requesting a feature that is not enabled for your organization (e.g., tier: "micro", tier: "high", or tier: "xhigh" enrichment)
• Calling any /monitors endpoint when Monitors are not enabled for your organization
• Creating or updating a monitor with the 5m frequency or micro tier when testing monitors are not enabled for your organization

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

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

{
  "detail": "Monitors are not enabled for your organization."
}

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

​

409 Conflict (Monitors)

• Triggering a monitor that is cancelled or paused
• Updating a cancelled monitor or switching one of its rows on or off
• Reusing a monitor idempotency key with different creation settings or file contents, or with an older explicit key whose original request cannot be verified
• Triggering a monitor, or changing its frequency or is_active, while its status is starting or failed, before every row from an uploaded file is added
• Sending a create request while an identical one, with the same idempotency key, is still being processed

{
  "detail": "This monitor is not active."
}

{
  "detail": "This request is already being processed. Retry shortly."
}

• For a paused monitor, resume it with POST /monitors/{monitor_id}/update and "is_active": true, then trigger it
• For a monitor whose status is starting, wait until it is active. For one whose status is failed, send the same upload request again, with the same file and settings, to finish it
• A cancelled monitor cannot be resumed or changed. Create a new monitor to start checks again
• For an idempotency conflict, retry with the original creation payload. Use a new key for a new monitor, or when an older explicit key cannot be verified
• If the request is still being processed, retry after a few seconds with the same payload and key; it returns what the first attempt created

​

502 Bad Gateway (Monitor Cancellation)

{
  "detail": "Monitor is cancelled, but its schedule could not be paused. Retry cancellation to finish cleanup."
}

​

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
• Monitor or row ID does not exist, or the monitor belongs to another team

{
  "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 (Monitors)

​

422 Validation Error (Workflows and Other Monitor Requests)

• Invalid workflow definition (empty blocks, incompatible block types)
• Missing required fields in create/update requests
• Invalid block or edge configuration
• Unknown fields in monitor create, update, row-toggle, source, or history-export JSON requests, such as frequncy instead of frequency
• Toggling a monitor row without the required JSON body {"is_active": false} or {"is_active": true}; the query parameter alone is not accepted

{
  "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
• Exceeded 120 requests per minute for your organization on POST /verify-email

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

• Implement exponential backoff and retry logic
• Wait the number of seconds in the Retry-After header when present, otherwise 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

​

503 Service Unavailable (Verify Email)

{
  "detail": "Email verification is temporarily unavailable. Retry shortly."
}

​

Rate Limits

• 500 requests per minute per API key
• 5 concurrent deep searches per organization
• 120 requests per minute per organization on POST /verify-email

• 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()

// For sync endpoints, set timeout to at least 15 minutes (900000 ms)
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 900000); // 15 minutes

try {
  const response = await fetch("https://api.sixtyfour.ai/people-intelligence", {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
    signal: controller.signal
  });
  clearTimeout(timeoutId);

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const result = await response.json();
} catch (error) {
  clearTimeout(timeoutId);
  if (error.name === 'AbortError') {
    console.error('Request timed out after 15 minutes');
  } else {
    throw error;
  }
}

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", "terminated", "timed_out"):
        print(f"Job {status['status']}: {status.get('error')}")
        break

    time.sleep(10)

// Start async job
const response = await fetch("https://api.sixtyfour.ai/people-intelligence-async", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const taskInfo = await response.json();
const taskId = taskInfo.task_id;

// Poll for results
while (true) {
  const statusResponse = await fetch(
    `https://api.sixtyfour.ai/job-status/${taskId}`,
    { headers: headers }
  );

  if (!statusResponse.ok) {
    throw new Error(`HTTP error! status: ${statusResponse.status}`);
  }

  const status = await statusResponse.json();

  if (status.status === "completed") {
    const results = status.result;
    break;
  } else if (["failed", "cancelled", "terminated", "timed_out"].includes(status.status)) {
    console.error(`Job ${status.status}: ${status.error || "Unknown error"}`);
    break;
  }

  // Wait 10 seconds before polling again
  await new Promise(resolve => setTimeout(resolve, 10000));
}

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}.

​

Verify Phone column mappings

​

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