Documentation Index
Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
Use this file to discover all available pages before exploring further.
The HopX API uses conventional HTTP status codes and returns detailed error responses to help you troubleshoot issues.
All errors return a JSON response with this structure:
{
"error": "Error message describing what went wrong",
"code": "ERROR_CODE",
"request_id": "req_abc123"
}
| Field | Type | Description |
|---|
error | string | Human-readable error message |
code | string | Machine-readable error code |
request_id | string | Request ID for support/debugging |
HTTP Status Codes
| Code | Meaning | Description |
|---|
| 200 | OK | Request succeeded |
| 202 | Accepted | Request accepted (async operation) |
| 204 | No Content | Request succeeded, no response body |
| 400 | Bad Request | Invalid request parameters |
| 401 | Unauthorized | Authentication failed or missing |
| 403 | Forbidden | Access denied |
| 404 | Not Found | Resource not found |
| 408 | Request Timeout | Request exceeded timeout |
| 409 | Conflict | Resource conflict (e.g., already exists) |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error |
| 503 | Service Unavailable | Service temporarily unavailable |
Error Codes
Authentication Errors
AUTHENTICATION_REQUIRED (401)
{
"error": "Authentication required",
"code": "AUTHENTICATION_REQUIRED",
"request_id": "req_abc123"
}
Authorization: Bearer $HOPX_API_KEY header.
INVALID_TOKEN (401)
{
"error": "Invalid or expired token",
"code": "INVALID_TOKEN",
"request_id": "req_abc123"
}
Request Errors
INVALID_REQUEST (400)
{
"error": "Invalid request: missing required field 'code'",
"code": "INVALID_REQUEST",
"request_id": "req_abc123"
}
RESOURCE_NOT_FOUND (404)
{
"error": "Sandbox not found",
"code": "RESOURCE_NOT_FOUND",
"request_id": "req_abc123"
}
CONFLICT (409)
{
"error": "Template already exists. Set update=true to update it.",
"code": "CONFLICT",
"request_id": "req_abc123"
}
update=true.
Execution Errors
EXECUTION_TIMEOUT (408)
{
"error": "Execution timeout after 60 seconds",
"code": "EXECUTION_TIMEOUT",
"request_id": "req_abc123"
}
CODE_EXECUTION_ERROR (500)
{
"success": false,
"stdout": "",
"stderr": "NameError: name 'x' is not defined\n",
"exit_code": 1,
"execution_time": 0.05
}
stderr field for error details and fix your code.
Resource Errors
PAYMENT_REQUIRED (402)
{
"error": "Payment required: credit limit exceeded",
"code": "PAYMENT_REQUIRED",
"request_id": "req_abc123"
}
RESOURCE_LIMIT_ERROR (429)
{
"error": "Sandbox limit reached (10/10)",
"code": "RESOURCE_LIMIT_ERROR",
"request_id": "req_abc123"
}
FORBIDDEN (403)
{
"error": "Path not allowed: /etc/passwd",
"code": "FORBIDDEN",
"request_id": "req_abc123"
}
/workspace, /tmp).
Rate Limiting
RATE_LIMIT_EXCEEDED (429)
{
"error": "Rate limit exceeded: 100 requests per minute",
"code": "RATE_LIMIT_EXCEEDED",
"request_id": "req_abc123",
"retry_after": 30
}
Service Errors
SERVICE_UNAVAILABLE (503)
{
"error": "Service temporarily unavailable",
"code": "SERVICE_UNAVAILABLE",
"request_id": "req_abc123"
}
INTERNAL_ERROR (500)
{
"error": "Internal server error",
"code": "INTERNAL_ERROR",
"request_id": "req_abc123"
}
request_id if issue persists.
Error Handling Best Practices
1. Check Status Codes
RESPONSE=$(curl -s -w "\n%{http_code}" https://api.hopx.dev/v1/sandboxes \
-H "Authorization: Bearer $HOPX_API_KEY")
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')
if [ "$HTTP_CODE" -ge 400 ]; then
echo "Error: $BODY"
exit 1
fi
2. Parse Error Responses
import requests
response = requests.post(
"https://api.hopx.dev/v1/sandboxes",
headers={"Authorization": "Bearer $HOPX_API_KEY"},
json={"template_id": "code-interpreter"}
)
if response.status_code >= 400:
error = response.json()
print(f"Error: {error['error']}")
print(f"Code: {error['code']}")
print(f"Request ID: {error['request_id']}")
exit(1)
3. Implement Retry Logic
import time
import requests
def create_sandbox_with_retry(max_retries=3):
for attempt in range(max_retries):
try:
response = requests.post(
"https://api.hopx.dev/v1/sandboxes",
headers={"Authorization": "Bearer $HOPX_API_KEY"},
json={"template_id": "code-interpreter"},
timeout=30
)
if response.status_code == 200:
return response.json()
# Retry on 5xx errors or rate limits
if response.status_code >= 500 or response.status_code == 429:
wait_time = 2 ** attempt # Exponential backoff
print(f"Retry {attempt + 1}/{max_retries} after {wait_time}s")
time.sleep(wait_time)
continue
# Don't retry on 4xx errors (except 429)
response.raise_for_status()
except requests.exceptions.RequestException as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)
raise Exception("Max retries exceeded")
4. Handle Specific Errors
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 401:
# Refresh token and retry
refresh_token()
response = requests.post(url, headers=headers, json=payload)
elif response.status_code == 404:
# Resource not found - create it
create_resource()
elif response.status_code == 429:
# Rate limited - wait and retry
time.sleep(60)
response = requests.post(url, headers=headers, json=payload)
Getting Support
When contacting support, always include:
- Request ID - From the error response
- Timestamp - When the error occurred
- API endpoint - The URL you called
- HTTP status code - The response status
- Error message - The full error response
Example support request:
Request ID: req_abc123
Timestamp: 2025-01-28T00:00:00Z
Endpoint: POST /v1/sandboxes
Status: 500
Error: Internal server error
Next Steps
