---

name: hex-common-errors description: 'Diagnose and fix Hex common errors and exceptions.

Use when encountering Hex errors, debugging failed requests,

or troubleshooting integration issues.

Trigger with phrases like "hex error", "fix hex",

"hex not working", "debug hex".

' allowed-tools: Read, Grep, Bash(curl:*) version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• hex
• data
• analytics compatibility: Designed for Claude Code

---

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

Overview

This reference triages project-run failures using status, aggregate telemetry, and opaque run IDs. It does not authorize copying SQL, cell output, data previews, or tokens into a ticket.

Prerequisites

• A safe sandbox probe, redacted correlation ID, endpoint class, and HTTP or terminal-run status.
• A scoped read-only diagnostic credential and named owner for any project, schedule, or access change.

Instructions

1. Classify authentication, authorization, project lookup, validation, quota, timeout, and terminal-run errors before changing configuration.
2. Reproduce once with the safe probe and capture only status, latency, quota, and opaque run ID.
3. Check scope, parameter schema, project state, quota, and downstream connection health in that order.
4. Make one reversible change at a time and escalate a redacted bundle when the error persists.

Output

Return error class, correlation ID, project scope, probe outcome, remediation attempted, and next owner. Do not include SQL, output, credentials, or identities.

Error Handling

Treat unknown destination, failed redaction, access expansion, or repeated non-idempotent run as a stop condition. Cancel or restore the prior revision rather than retrying with broader scope.

Examples

status=429; project=proj-sandbox-12; correlation=run-opaque-11; action=bounded-backoff; safe_probe=recovered supports a safe handoff.

Resources

• Hex API Reference

Next Steps

For debugging, see hex-debug-bundle.