Troubleshooting

​

How to read an error response

{
  "error_code": "quota_exceeded",
  "message": "Concurrent sandbox limit reached",
  "status": 429
}

{
  "error": {
    "code": "AUTH.PERMISSION_DENIED",
    "message": "Insufficient permissions for this resource",
    "request_id": "req_abc123xyz"
  }
}

{
  "error_code": "invalid_request",
  "message": "fleet_id is required",
  "status": 400
}

{
  "error": {
    "code": "PROVIDER_AUTH_FAILED",
    "message": "OAuth token for provider expired"
  }
}

​

Authentication

• Confirm your API key or client credentials are correct and not expired.
• Verify the credential is set: HEXEL_API_KEY, or HEXEL_CLIENT_ID + HEXEL_CLIENT_SECRET.
• Access tokens last 15 minutes. If you exchange them manually with curl, re-exchange after expiry. The SDKs refresh automatically.

• Your credential is valid but lacks the required permission. Check the role assigned to the service user. Permissions follow the pattern data-platform:<resource>:<action> or orchestrator:task:write.

• Each credential is scoped to a workspace and environment. Use the credential for the environment you intend to operate in.

​

Compute

• Verify your image implements the agent contract: GET /health returning {"status": "ok"} and GET /.well-known/agent.json.
• Check logs for startup errors.
• For private registries, confirm pull credentials are correct.

• Deploy is only available via the REST API (POST /compute/v1/agents/{agent_id}/instances) or the hexel CLI (hexel compute instance deploy <agent-id>). There is no instance.deploy() in the SDKs.

• Inspect logs for the cause, fix the image or configuration, then redeploy with client.compute.instance.redeploy() or hexel compute instance redeploy.

• The requested tier has no available capacity. There is no auto-fallback to another tier. Wait and retry, or use a different tier if your workload allows it.

• You’ve hit the ConcurrentSandboxes limit. Release idle sandboxes or request a quota increase via Support.

​

Data Platform

• The knowledge store, memory store, or datasource ID does not exist in the current environment. Verify the ID and that your credential targets the correct environment.

• A request parameter is invalid (e.g., chunk_size out of range, missing required field). Check the error message for the specific field.

• Tune chunk_size, chunk_overlap, and score_threshold. Keep stores focused on one domain. See Knowledge Stores.

• Confirm the source has a sync schedule and check Syncs for failed runs.

​

Orchestration

• The plan needs approval. Review it via Approvals; pending approvals expire after 24 hours.

• Stream or replay the task to see where it failed. Task streams emit task.submitted → task.state → task.error → task.failed events with the error detail in the payload.

• Orchestration is limited to 100 requests per organization per minute. Batch submissions or implement a queue with backoff.

​

Tool Gateway

• Confirm the provider account is connected and the agent is bound to the toolkit.
• Check that the tool is not excluded by a workspace group allow-list.

• Use asynchronous execution and poll the call result. See Executing Tools.

​

Getting help faster

1. Capture the exact error response (including error_code and request_id where present).
2. Note the environment_id, workspace_id, and resource identifier (agent, instance, task, sandbox, or store).
3. Check Logs for the failing resource at the time of failure.
4. Reach out through Support with those details.

​

Related pages