Skill

hex-common-errors

Diagnoses and fixes common Hex API errors: 401/403/404/429 auth/rate limits, ERRORED/KILLED runs. Includes curl tests for tokens/projects.

api-development

data-engineering

npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin hex-pack

Tool Access

This skill is limited to using the following tools:

ReadGrepBash(curl:*)

Preview

**Cause:** Token invalid, expired, or missing.

SKILL.md

Similar Skills

hex-hello-world

1.9k

Generates TypeScript code for Hex API: list projects, trigger runs with params, poll completion, access results. For new integrations, setup testing, or API learning.

5 tools

hex-pack

insforge-debug

Diagnoses errors, bugs, performance issues, and failures in InsForge projects from frontend SDK errors to backend infrastructure via CLI commands for logs/status and AI-assisted suggestions.

insforge-agent-skills

api-error-handling

180

Implements API error handling with standardized responses, logging, monitoring, retry logic, circuit breakers, and validation patterns for Node.js and Python APIs.

4 files

aj-geddes-useful-ai-prompts-4

Stats

Parent Repo Stars1854

Parent Repo Forks248

Last CommitMar 22, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

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.