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