hex-common-errors

# 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 ```bash # 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 - [Hex API Reference](https://learn.hex.tech/docs/api/api-reference) ## Next Steps For debugging, see `hex-debug-bundle`.