Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/juicebox-pack/skills/juicebox-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill juicebox-common-errors. Copyright stays with the author (MIT).

Juicebox Common Errors

Overview

Juicebox provides AI-powered people search and analysis for recruiting and research workflows. API integrations cover search queries, profile enrichment, dataset operations, and quota management. Common errors include dataset format mismatches when uploading CSVs, analysis timeouts on large candidate pools, and quota exhaustion on free or starter plans. The quota system counts individual profile enrichments separately from search queries, which often surprises new integrators. This reference covers HTTP errors, business logic failures, and recovery strategies for reliable Juicebox integrations.

Error Reference

Error Handler

interface JuiceboxError {
  code: number;
  message: string;
  category: "auth" | "rate_limit" | "validation" | "timeout";
}

function classifyJuiceboxError(status: number, body: string): JuiceboxError {
  if (status === 401 || status === 403) {
    return { code: status, message: body, category: "auth" };
  }
  if (status === 429) {
    return { code: 429, message: "Rate limited", category: "rate_limit" };
  }
  if (status === 408) {
    return { code: 408, message: body, category: "timeout" };
  }
  return { code: status, message: body, category: "validation" };
}

Debugging Guide

Authentication Errors

Juicebox API keys are passed via Authorization: Bearer header. Keys are scoped per workspace. If you receive 401, verify the key has not been rotated at app.juicebox.ai > Settings. A 403 indicates quota exhaustion, not a permissions issue -- check your plan's remaining searches.

Rate Limit Errors

The API enforces 30 requests/minute per key. Batch profile enrichment calls where possible. Use the Retry-After response header to determine wait time. For bulk operations, use the dataset upload endpoint instead of individual search queries.

Validation Errors

Dataset uploads require CSV format with headers matching the Juicebox schema: name, title, company are required columns. Optional enrichment columns include email, linkedin_url, and location. Files over 50MB or 100K rows are rejected -- split into chunks. Analysis queries that exceed 60 seconds timeout with 408; narrow filters by adding location, title, or company constraints to reduce result set size.

Error Handling

Quick Diagnostic

# Verify API connectivity and key validity
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $JUICEBOX_API_KEY" \
  https://api.juicebox.ai/v1/health

Prerequisites

• A sandbox workspace, synthetic fixture, approved diagnostic scope, secret references, source/destination allowlists, suppression controls, and a designated incident owner.

Instructions

1. Reproduce failures with synthetic inputs only; reject live-record export, unapproved sources/destinations, and literal credentials in commands or logs.
2. Capture aggregate status, error class, and quota evidence, then verify redaction, suppression, retention, and contacts_exported=0.
3. Stop the canary on scope, policy, quota, or retention drift; revoke temporary access and restore the known-good configuration.
4. Preserve a redacted diagnostic receipt only for the approved window, then delete staged artifacts.

Output

Produce an error-triage receipt with environment, synthetic fixture classification, error class, aggregate status/quota signal, suppression/no-export/redaction checks, incident owner, cleanup proof, and rollback reference. Exclude request payloads, contacts, and credentials.

Examples

env=ci-synthetic; error=429; retries=backoff; quota=within-budget; suppression=pass; contacts_exported=0; cleanup=verified is a valid triage record.

Resources

• Juicebox Documentation
• Juicebox API Reference

Next Steps

See juicebox-debug-bundle.