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

# Handling Errors

> Error codes, rate limits, and common troubleshooting steps for the Sixtyfour API.

## Error Response Format

All Sixtyfour API errors return a JSON response with a consistent structure:

```json theme={null}
{
  "error": "Error Type",
  "message": "Detailed error message"
}
```

Some endpoints may use an alternative format:

```json theme={null}
{
  "detail": "Error description"
}
```

Workflows and other endpoints may return 422 validation errors with a structured `detail` array:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "workflow_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## HTTP Status Codes

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

| Status Code | Meaning               | Description                                                            |
| ----------- | --------------------- | ---------------------------------------------------------------------- |
| 200         | OK                    | Request succeeded                                                      |
| 400         | Bad Request           | Invalid request body, missing required fields, or malformed data       |
| 401         | Unauthorized          | Missing or invalid API key                                             |
| 402         | Payment Required      | Insufficient balance to cover the estimated cost of a bulk job         |
| 403         | Forbidden             | Feature not enabled for your organization (e.g., high-tier enrichment) |
| 404         | Not Found             | Resource not found (e.g., workflow or run ID)                          |
| 422         | Validation Error      | Invalid request parameters; see `detail` array for field-level errors  |
| 429         | Too Many Requests     | Rate limit exceeded                                                    |
| 500         | Internal Server Error | Server error - retry after a brief wait                                |

## Common Error Types

### 400 Bad Request

**Causes:**

* 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](/api-reference/search/search-exclusions)

**Examples:**

```json theme={null}
{
  "error": "Bad Request",
  "message": "Invalid company data"
}
```

```json theme={null}
{
  "error": "Bad Request",
  "message": "Invalid lead data"
}
```

```json theme={null}
{
  "detail": "Lead data is required"
}
```

```json theme={null}
{
  "error": "Bad Request",
  "message": "Missing required field: qualification_criteria"
}
```

**How to fix:**

* 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](/api-reference/webhooks/incoming)) or `specs_override.resource_handle_id` for `read_csv` workflows ([Workflow Execution](/api-reference/workflows/workflows-execution)). `webhook_payload` requires API key or OAuth auth — JWT (dashboard session) is rejected.

### 401 Unauthorized

**Causes:**

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

**Example:**

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**How to fix:**

* 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](https://app.sixtyfour.ai)

### 402 Payment Required

**Causes:**

* Your balance doesn't cover the estimated cost of a [bulk intelligence](/api-reference/endpoint/bulk-intelligence) job (`rows × per-row tier price`)

**How to fix:**

* Add credits in the [dashboard](https://app.sixtyfour.ai) before resubmitting
* Reduce the row count or use a cheaper tier to lower the estimated cost

Nothing is charged when a request returns 402.

### 403 Forbidden

**Causes:**

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

**Examples:**

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

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

**How to fix:**

* 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)

**Causes:**

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

**Example:**

```json theme={null}
{
  "detail": "Workflow not found"
}
```

**How to fix:**

* 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)

**Causes:**

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

**Example:**

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "workflow_definition", "blocks"],
      "msg": "blocks cannot be empty",
      "type": "value_error"
    }
  ]
}
```

**How to fix:**

* 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

**Causes:**

* Exceeded the rate limit of 500 requests per minute

**Example:**

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded"
}
```

**How to fix:**

* 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

**Causes:**

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

**Example:**

```json theme={null}
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}
```

**How to fix:**

* Wait a few seconds and retry the request
* Implement retry logic with exponential backoff
* If the error persists, contact support at [support@sixtyfour.ai](mailto:support@sixtyfour.ai)

## Rate Limits

The Sixtyfour API enforces the following rate limits:

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

Rate limit information may be included in response headers (if available):

* `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**

```python theme={null}
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**

For processing multiple items, use async endpoints (`/company-intelligence-async`, `/people-intelligence-async`) or the [Workflows API](/api-reference/workflows/workflows-overview) instead of making many synchronous calls.

3. **Implement Request Queuing**

Queue requests and process them at a controlled rate to stay under the limit.

## Timeout Issues

### Long-Running Requests

Some endpoints perform deep research and can take several minutes:

* **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

**Solutions:**

1. **Set Appropriate Timeouts**

<CodeGroup>
  ```python Python theme={null}
  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()
  ```

  ```javascript JavaScript theme={null}
  // 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;
    }
  }
  ```
</CodeGroup>

2. **Use Async Endpoints**

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```javascript JavaScript theme={null}
  // 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 (status.status === "failed" || status.status === "cancelled") {
      console.error(`Job ${status.status}: ${status.error || "Unknown error"}`);
      break;
    }

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

3. **Use Webhooks**

Configure webhooks to receive notifications when async jobs complete. See [Outgoing Webhooks](/api-reference/webhooks/outgoing).

## Common Troubleshooting Scenarios

### Issue: "Invalid API key" error

**Check:**

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

**Solution:** Get your API key from the [dashboard](https://app.sixtyfour.ai) and verify it's correctly included in the header.

***

### Issue: Request times out

**Check:**

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

**Solution:** Use async endpoints or increase client timeout to at least 15 minutes (900 seconds).

***

### Issue: Empty or incomplete results

**Check:**

* 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?

**Solution:**

* 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

**Check:**

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

**Solution:**

* 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

**Check:**

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

**Solution:** Validate your JSON payload and compare against the endpoint documentation.

***

### Issue: Workflow run stuck or not progressing

**Check:**

* 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?

**Solution:**

* 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

**Check:**

* 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?

**Solution:**

* Log the raw body, the `Sixtyfour-Signature` header, and the HMAC your server computes; compare against what we sent.
* See [Signing Secrets & Verification](/api-reference/webhooks/signing-secrets) 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

If you're experiencing issues not covered in this guide:

1. Check the [API Reference](/api-quick-start) for endpoint-specific requirements
2. Review the [starter notebooks](/starter-notebooks/company-intelligence-tutorial) for working examples
3. Contact support at [support@sixtyfour.ai](mailto: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