juicebox-common-errors

Included with Lifetime

$97 forever

Diagnose and fix Juicebox API errors. Trigger: "juicebox error", "fix juicebox", "debug juicebox".

Backend & APIssaasrecruitingjuicebox

What this skill does

# 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

| Code | Message | Cause | Fix |
|------|---------|-------|-----|
| `400` | `Invalid query format` | Malformed search query or empty filters | Ensure query is non-empty; validate filter field names |
| `401` | `invalid_api_key` | API key missing or revoked | Verify key at app.juicebox.ai > Settings > API |
| `403` | `quota_exceeded` | Plan search limit reached | Check quota in dashboard; upgrade plan or wait for reset |
| `404` | `Profile not found` | Candidate removed or profile unavailable | Re-run search to find updated profile data |
| `408` | `Analysis timeout` | Complex query exceeded 60s limit | Reduce dataset size or narrow search filters |
| `413` | `Dataset too large` | Upload exceeds 50MB or 100K row limit | Split dataset into smaller chunks before upload |
| `422` | `Invalid dataset format` | CSV headers don't match expected schema | Use template from Juicebox docs; required: `name`, `title`, `company` |
| `429` | `Rate limited` | Exceeded 30 requests/minute | Check `Retry-After` header; implement exponential backoff |

## Error Handler

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

| Scenario | Pattern | Recovery |
|----------|---------|----------|
| Quota exceeded mid-batch | 403 after N successful calls | Track remaining quota via response headers; pause and resume |
| Dataset upload rejected | Invalid CSV format | Download template, reformat, and retry |
| Analysis timeout | Large candidate pool | Add location/title/company filters to narrow scope |
| Profile data stale | 404 on enrichment | Re-run search query to get current profile URLs |
| Rate limit during bulk search | 429 on sequential calls | Switch to dataset upload for bulk operations |

## Quick Diagnostic

```bash
# 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
```

## Resources

- [Juicebox Documentation](https://docs.juicebox.work)
- [Juicebox API Reference](https://api.juicebox.ai/docs)

## Next Steps

See `juicebox-debug-bundle`.

Files: 3

Size: 12.8 KB

Complexity: 31/100

Category: Backend & APIs

Source: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/juicebox-pack/skills/juicebox-common-errors

Related in Backend & APIs

jfrog

Included

Interact with the JFrog Platform via the JFrog CLI and REST/GraphQL APIs. Use this skill when the user wants to manage Artifactory repositories, upload or download artifacts, manage builds, configure permissions, manage users and groups, work with access tokens, configure JFrog CLI servers, search artifacts, manage properties, set up replication, manage JFrog Projects, run security audits or scans, look up CVE details, query exposures scan results from JFrog Advanced Security, manage release bundles and lifecycle operations, aggregate or export platform data, or perform any JFrog Platform administration task. Also use when the user mentions jf, jfrog, artifactory, xray, distribution, evidence, apptrust, onemodel, graphql, workers, mission control, curation, advanced security, exposures, or any JFrog product name.

Backend & APIsscripts

cupynumeric-migration-readiness

Included

Pre-migration readiness assessor for porting NumPy to cuPyNumeric. Use BEFORE substantial porting work begins when the user asks whether code will scale on GPU, whether they should migrate to cuPyNumeric, which NumPy patterns transfer cleanly, what must be refactored before porting, or mentions pre-port assessment, scaling analysis, or refactor planning. Inspect the user's source code, look up NumPy usage, cross-reference the cuPyNumeric API support manifest, and distinguish distributed-scaling-friendly patterns from blockers such as unsupported APIs, scalar synchronization, host round-trips, Python/object-heavy control flow, shape/data-dependent branching, and in-place mutation hazards. Produce a verdict of READY, LIGHT REFACTOR, SIGNIFICANT REFACTOR, or NOT RECOMMENDED, with concrete refactor pointers.

Backend & APIsscripts

alibabacloud-data-agent-skill

Included

Invoke Alibaba Cloud Apsara Data Agent for Analytics via CLI to perform natural language-driven data analysis on enterprise databases. Data Agent for Analytics is an intelligent data analysis agent developed by Alibaba Cloud Database team for enterprise users. It automatically completes requirement analysis, data understanding, analysis insights, and report generation based on natural language descriptions. This tool supports: discovering data resources (instances/databases/tables) managed in DMS, initiating query or deep analysis sessions, real-time progress tracking, and retrieving analysis conclusions and generated reports. Use this Skill when users need to query databases, analyze data trends, generate data reports, ask questions in natural language, or mention "Data Agent", "data analysis", "database query", "SQL analysis", "data insights".

Backend & APIsscripts

token-optimizer

Included

Reduce OpenClaw token usage and API costs through smart model routing, heartbeat optimization, budget tracking, and native 2026.2.15 features (session pruning, bootstrap size limits, cache TTL alignment). Use when token costs are high, API rate limits are being hit, or hosting multiple agents at scale. The 4 executable scripts (context_optimizer, model_router, heartbeat_optimizer, token_tracker) are local-only — no network requests, no subprocess calls, no system modifications. Reference files (PROVIDERS.md, config-patches.json) document optional multi-provider strategies that require external API keys and network access if you choose to use them. See SECURITY.md for full breakdown.

Backend & APIsscripts

resend-cli

Included

Use this skill when the task is specifically about operating Resend from an AI agent, terminal session, or CI job via the official resend CLI: installing/authenticating the CLI, sending/listing/updating/cancelling emails, batch sends, domains and DNS, webhooks and local listeners, inbound receiving, contacts, topics, segments, broadcasts, templates, API keys, profiles, or debugging Resend CLI/API failures. Trigger on mentions of Resend CLI, `resend`, `resend doctor`, `resend emails send`, `resend domains`, `resend webhooks listen`, `resend emails receiving`, or agent-friendly terminal automation.

Backend & APIsscripts

alibabacloud-odps-maxframe-coding

Included

Use this skill for MaxFrame SDK development and documentation navigation on Alibaba Cloud MaxCompute (ODPS). Helps answer MaxFrame API, concept, official example, and supported pandas API questions; create data processing programs; read/write MaxCompute tables; debug jobs (remote or local); and build custom DPE runtime images. Trigger when users mention MaxFrame, MaxCompute with MaxFrame, ODPS table processing, DPE runtime, MaxFrame docs/examples, DataFrame/Tensor operations, or GPU runtime setup. Works for both English and Chinese queries about Alibaba Cloud data processing with MaxFrame.

Backend & APIsscripts