jeremylongshore Hex Common Errors
Error Reference
401 Unauthorized
Cause: Token invalid, expired, or missing. Fix: Regenerate token in Hex workspace settings.
403 Forbidden — Read-Only Token
Cause: Token has "Read projects" scope but RunProject requires "Run projects". Fix: Create new token with "Run projects" scope.
404 Not Found — Project
Cause: Project ID wrong or project not published. Fix: Verify project ID. Only published projects can be run via API.
429 Too Many Requests
Cause: RunProject is limited to 20 requests/min, 60/hr.
Fix: Queue runs with delays. See hex-rate-limits.
Run Status: ERRORED
Cause: SQL query, Python code, or connection error in the project. Fix: Open the project in Hex UI and check the error in the run history.
Run Status: KILLED
Cause: Run exceeded timeout or was manually cancelled. Fix: Optimize slow queries. Increase timeout in API trigger.
Quick Diagnostics
# Test token
curl -s -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $HEX_API_TOKEN" \
https://app.hex.tech/api/v1/projects
# List recent runs for a project
curl -s -H "Authorization: Bearer $HEX_API_TOKEN" \
https://app.hex.tech/api/v1/project/PROJECT_ID/runs | python3 -m json.tool
Resources
Next Steps
For debugging, see hex-debug-bundle.
Source: jeremylongshore/claude-code-plugins-plus-skills → plugins/saas-packs/hex-pack/skills/hex-common-errors/SKILL.md