Juicebox Common Errors

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