Error Handling

HITL.sh APIs use conventional HTTP status codes and provide detailed error messages to help you debug issues quickly. All errors follow a consistent format for easy parsing and handling.

Error Response Format

All API errors return a JSON response with the following structure:

{
  "error": true,
  "msg": "Human-readable error description",
  "data": {
    // Additional error details (optional)
  }
}

Error Response Fields

boolean

Always true for error responses

string

Human-readable error message describing what went wrong

object

Additional error context, validation details, or debugging information (optional)

HTTP Status Codes

2xx Success

200 OK

Request succeeded. Response contains the requested data.

{
  "error": false,
  "msg": "Operation completed successfully",
  "data": { /* response data */ }
}

201 Created

Resource was created successfully.

{
  "error": false,
  "msg": "Loop created successfully",
  "data": { /* created resource */ }
}

4xx Client Errors

400 Bad Request

Request data is invalid or malformed.Common causes:

Missing required fields
Invalid field values
Malformed JSON
Validation failures

Invalid request body:

{
  "error": true,
  "msg": "Invalid request body"
}

Invalid ID format:

{
  "error": true,
  "msg": "Invalid loop ID format"
}

{
  "error": true,
  "msg": "Invalid request ID format"
}

Missing required fields:

{
  "error": true,
  "msg": "Loop name is required"
}

{
  "error": true,
  "msg": "Loop icon is required"
}

{
  "error": true,
  "msg": "Request text is required"
}

{
  "error": true,
  "msg": "timeout_seconds is required for time-sensitive requests"
}

{
  "error": true,
  "msg": "Image URL is required when type is image"
}

Invalid configuration:

{
  "error": true,
  "msg": "Invalid response configuration",
  "data": "options array required for select response type"
}

{
  "error": true,
  "msg": "Invalid default response",
  "data": "default_response must match one of the configured options"
}

State validation errors:

{
  "error": true,
  "msg": "No active members found in the loop"
}

{
  "error": true,
  "msg": "Request cannot be cancelled in current state"
}

{
  "error": true,
  "msg": "Feedback can only be added to completed requests"
}

401 Unauthorized

Authentication is missing or invalid.Common causes:

Missing API key
Invalid API key
Malformed authorization header
Inactive API key

Missing Authorization header:

{
  "error": true,
  "msg": "Missing Authorization header"
}

Invalid header format:

{
  "error": true,
  "msg": "Invalid Authorization header format. Use 'Bearer <api_key>'"
}

Empty API key:

{
  "error": true,
  "msg": "Empty API key"
}

Invalid API key:

{
  "error": true,
  "msg": "Invalid API key"
}

Inactive API key:

{
  "error": true,
  "msg": "API key is inactive"
}

API key required:

{
  "error": true,
  "msg": "API key required"
}

403 Forbidden

Authentication is valid but access is denied.Common causes:

Not the resource owner (loop creator)
Not a member of the loop
Insufficient permissions for the operation

Access denied to loop:

{
  "error": true,
  "msg": "Access denied to this loop"
}

Access denied to request:

{
  "error": true,
  "msg": "Access denied to this request"
}

Creator-only operations:Only loop creators can create requests:

{
  "error": true,
  "msg": "Only loop creators can create requests"
}

Only loop creator can update:

{
  "error": true,
  "msg": "Only loop creator can update the loop"
}

Only loop creator can delete:

{
  "error": true,
  "msg": "Only loop creator can delete the loop"
}

Only loop creator can remove members:

{
  "error": true,
  "msg": "Only loop creator can remove members"
}

Loop creator cannot remove themselves:

{
  "error": true,
  "msg": "Loop creator cannot remove themselves"
}

404 Not Found

The requested resource doesn’t exist.Common causes:

Invalid resource ID
Resource was deleted
Typo in endpoint URL
Resource doesn’t belong to your account

Loop not found:

{
  "error": true,
  "msg": "Loop not found"
}

Request not found:

{
  "error": true,
  "msg": "Request not found"
}

User is not a member:

{
  "error": true,
  "msg": "User is not a member of this loop"
}

429 Too Many Requests

Rate limit has been exceeded. Limits reset at the top of each hour.Rate limit exceeded:

{
  "error": true,
  "msg": "Rate limit exceeded. Maximum 100 requests per hour per API key."
}

API key usage limit exceeded:

{
  "error": true,
  "msg": "API key usage limit exceeded"
}

Response headers (included in all responses):

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704204000

The X-RateLimit-Reset header contains a Unix timestamp indicating when the rate limit will reset (top of the next hour).

5xx Server Errors

500 Internal Server Error

An unexpected error occurred on our servers.Common server errors:Database errors:

{
  "error": true,
  "msg": "Failed to retrieve loops"
}

{
  "error": true,
  "msg": "Failed to retrieve loop"
}

{
  "error": true,
  "msg": "Failed to create loop"
}

{
  "error": true,
  "msg": "Failed to update loop"
}

{
  "error": true,
  "msg": "Failed to retrieve requests"
}

{
  "error": true,
  "msg": "Failed to retrieve request"
}

{
  "error": true,
  "msg": "Failed to cancel request"
}

{
  "error": true,
  "msg": "Failed to add feedback"
}

User information errors:

{
  "error": true,
  "msg": "Failed to get user information"
}

What to do:

Retry the request after a short delay
Check our status page at status.hitl.sh
Contact support if the issue persists

502 Bad Gateway

Gateway or proxy error, usually temporary.

{
  "error": true,
  "msg": "Service temporarily unavailable"
}

503 Service Unavailable

Service is temporarily unavailable, usually due to maintenance.

{
  "error": true,
  "msg": "Service temporarily unavailable"
}

Common Error Scenarios

Validation Errors

Request Text Too Long:

{
  "error": true,
  "msg": "Validation failed",
  "data": "request_text must be between 1 and 2000 characters"
}

Invalid Response Configuration:

{
  "error": true,
  "msg": "Invalid response configuration",
  "data": "options array required for select response type"
}

Invalid Enum Value:

{
  "error": true,
  "msg": "Validation failed",
  "data": "priority must be one of: low, medium, high, critical"
}

Resource Access Errors

Loop Not Found:

{
  "error": true,
  "msg": "Loop not found"
}

Request Already Cancelled:

{
  "error": true,
  "msg": "Request cannot be cancelled in current state"
}

No Active Members:

{
  "error": true,
  "msg": "No active members found in the loop"
}

Authentication Errors

Missing API Key:

{
  "error": true,
  "msg": "API key required"
}

Invalid API Key Format:

{
  "error": true,
  "msg": "Invalid API key format"
}

Expired Session:

{
  "error": true,
  "msg": "Session has expired. Please log in again."
}

Error Handling Best Practices

1. Implement Retry Logic

Use exponential backoff for transient errors:

import time
import random
import requests

def make_request_with_retry(url, headers, data=None, max_retries=3):
    retryable_status_codes = [429, 500, 502, 503, 504]
    
    for attempt in range(max_retries):
        try:
            if data:
                response = requests.post(url, headers=headers, json=data)
            else:
                response = requests.get(url, headers=headers)
            
            if response.status_code not in retryable_status_codes:
                return response
            
            if attempt < max_retries - 1:  # Don't delay on last attempt
                # Exponential backoff with jitter
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(2 ** attempt)
    
    return response

async function makeRequestWithRetry(url, options, maxRetries = 3) {
    const retryableStatusCodes = [429, 500, 502, 503, 504];
    
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            const response = await fetch(url, options);
            
            if (!retryableStatusCodes.includes(response.status)) {
                return response;
            }
            
            if (attempt < maxRetries - 1) {
                // Exponential backoff with jitter
                const delay = (2 ** attempt) * 1000 + Math.random() * 1000;
                await new Promise(resolve => setTimeout(resolve, delay));
            }
            
        } catch (error) {
            if (attempt === maxRetries - 1) {
                throw error;
            }
            await new Promise(resolve => setTimeout(resolve, 2 ** attempt * 1000));
        }
    }
}

2. Handle Rate Limits Gracefully

import time
import requests

class HITLAPIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.hitl.sh/v1"
        
    def make_request(self, method, endpoint, data=None):
        url = f"{self.base_url}{endpoint}"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }
        
        response = requests.request(method, url, headers=headers, json=data)
        
        if response.status_code == 429:
            # Extract reset time from response
            reset_time = response.headers.get('X-RateLimit-Reset')
            if reset_time:
                wait_time = int(reset_time) - int(time.time())
                if wait_time > 0:
                    print(f"Rate limited. Waiting {wait_time} seconds...")
                    time.sleep(wait_time)
                    # Retry the request
                    return self.make_request(method, endpoint, data)
        
        return response

class HITLAPIClient {
    constructor(apiKey) {
        this.apiKey = apiKey;
        this.baseUrl = 'https://api.hitl.sh/v1';
    }
    
    async makeRequest(method, endpoint, data = null) {
        const url = `${this.baseUrl}${endpoint}`;
        const options = {
            method,
            headers: {
                'Authorization': `Bearer ${this.apiKey}`,
                'Content-Type': 'application/json'
            }
        };
        
        if (data) {
            options.body = JSON.stringify(data);
        }
        
        const response = await fetch(url, options);
        
        if (response.status === 429) {
            const resetTime = response.headers.get('X-RateLimit-Reset');
            if (resetTime) {
                const waitTime = parseInt(resetTime) - Math.floor(Date.now() / 1000);
                if (waitTime > 0) {
                    console.log(`Rate limited. Waiting ${waitTime} seconds...`);
                    await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
                    return this.makeRequest(method, endpoint, data);
                }
            }
        }
        
        return response;
    }
}

3. Validate Requests Client-Side

Implement client-side validation to catch errors early:

def validate_create_request_payload(payload):
    """Validate request payload before sending to API"""
    errors = []
    
    # Required fields
    required_fields = ['processing_type', 'type', 'priority', 'request_text', 
                      'response_type', 'response_config', 'default_response', 'platform']
    
    for field in required_fields:
        if field not in payload or not payload[field]:
            errors.append(f"{field} is required")
    
    # Enum validations
    if 'processing_type' in payload:
        valid_processing_types = ['time-sensitive', 'deferred']
        if payload['processing_type'] not in valid_processing_types:
            errors.append(f"processing_type must be one of: {', '.join(valid_processing_types)}")
    
    if 'priority' in payload:
        valid_priorities = ['low', 'medium', 'high', 'critical']
        if payload['priority'] not in valid_priorities:
            errors.append(f"priority must be one of: {', '.join(valid_priorities)}")
    
    # Custom validations
    if payload.get('processing_type') == 'time-sensitive' and 'timeout_seconds' not in payload:
        errors.append("timeout_seconds is required for time-sensitive requests")
    
    if 'timeout_seconds' in payload:
        timeout = payload['timeout_seconds']
        if not isinstance(timeout, int) or timeout < 60 or timeout > 86400:
            errors.append("timeout_seconds must be between 60 and 86400")
    
    return errors

function validateCreateRequestPayload(payload) {
    const errors = [];
    
    // Required fields
    const requiredFields = ['processing_type', 'type', 'priority', 'request_text', 
                           'response_type', 'response_config', 'default_response', 'platform'];
    
    for (const field of requiredFields) {
        if (!payload[field]) {
            errors.push(`${field} is required`);
        }
    }
    
    // Enum validations
    if (payload.processing_type) {
        const validProcessingTypes = ['time-sensitive', 'deferred'];
        if (!validProcessingTypes.includes(payload.processing_type)) {
            errors.push(`processing_type must be one of: ${validProcessingTypes.join(', ')}`);
        }
    }
    
    if (payload.priority) {
        const validPriorities = ['low', 'medium', 'high', 'critical'];
        if (!validPriorities.includes(payload.priority)) {
            errors.push(`priority must be one of: ${validPriorities.join(', ')}`);
        }
    }
    
    // Custom validations
    if (payload.processing_type === 'time-sensitive' && !payload.timeout_seconds) {
        errors.push('timeout_seconds is required for time-sensitive requests');
    }
    
    if (payload.timeout_seconds) {
        const timeout = payload.timeout_seconds;
        if (!Number.isInteger(timeout) || timeout < 60 || timeout > 86400) {
            errors.push('timeout_seconds must be between 60 and 86400');
        }
    }
    
    return errors;
}

4. Log Errors for Debugging

Implement comprehensive error logging:

import logging
import json

logger = logging.getLogger(__name__)

def log_api_error(response, endpoint, payload=None):
    """Log API errors with context for debugging"""
    try:
        error_data = response.json()
    except:
        error_data = {"msg": "Failed to parse error response"}
    
    log_entry = {
        "endpoint": endpoint,
        "status_code": response.status_code,
        "error_message": error_data.get("msg", "Unknown error"),
        "error_data": error_data.get("data"),
        "request_payload": payload,
        "response_headers": dict(response.headers)
    }
    
    logger.error(f"API Error: {json.dumps(log_entry, indent=2)}")
    
    return log_entry

# Usage
response = make_api_request(url, payload)
if response.status_code >= 400:
    log_api_error(response, endpoint, payload)

function logAPIError(response, endpoint, payload = null) {
    const logEntry = {
        endpoint,
        status: response.status,
        statusText: response.statusText,
        requestPayload: payload,
        timestamp: new Date().toISOString()
    };
    
    response.json().then(errorData => {
        logEntry.errorMessage = errorData.msg || 'Unknown error';
        logEntry.errorData = errorData.data;
        
        console.error('API Error:', JSON.stringify(logEntry, null, 2));
        
        // Send to your logging service
        // sendToLoggingService(logEntry);
    }).catch(() => {
        logEntry.errorMessage = 'Failed to parse error response';
        console.error('API Error:', JSON.stringify(logEntry, null, 2));
    });
    
    return logEntry;
}

Debugging Guide

Common Issues and Solutions

API Key Not Working

Symptoms: Getting 401 Unauthorized errorsDebugging steps:

Verify API key is correct (no extra spaces)
Check header format: Authorization: Bearer your_key_here
Ensure key hasn’t been revoked in dashboard
Try generating a new API key

# Test API key
curl -v -H "Authorization: Bearer your_api_key" https://api.hitl.sh/v1/api/loops

Request Validation Failing

Symptoms: Getting 400 Bad Request with validation errorsDebugging steps:

Check required fields are present
Verify enum values are correct
Validate field types and formats
Check field length constraints

# Debug validation
import json

payload = {
    "name": "Test Loop",
    "icon": "test"
}

print("Payload:", json.dumps(payload, indent=2))

# Check against API requirements
required_fields = ["name", "icon"]
for field in required_fields:
    if field not in payload:
        print(f"Missing required field: {field}")

Rate Limit Issues

Symptoms: Getting 429 Too Many RequestsDebugging steps:

Check rate limit headers in response
Implement exponential backoff
Consider upgrading API tier
Cache responses where possible

# Check rate limit status
curl -I -H "Authorization: Bearer your_api_key" https://api.hitl.sh/v1/api/loops

# Look for these headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 0
# X-RateLimit-Reset: 1642237200

Timeout Errors

Symptoms: Requests timing out or 504 errorsDebugging steps:

Check our status page: status.hitl.sh
Increase request timeout in your client
Try the request again after a delay
Contact support if issue persists

# Increase timeout
import requests

response = requests.get(
    url, 
    headers=headers, 
    timeout=30  # 30 second timeout
)

Request/Response Debugging

Enable verbose logging to see full HTTP requests and responses:

# Use -v flag for verbose output
curl -v -H "Authorization: Bearer your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"name": "Test Loop", "icon": "test"}' \
     https://api.hitl.sh/v1/api/loops

import requests
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("requests.packages.urllib3").setLevel(logging.DEBUG)
logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)

response = requests.post(url, headers=headers, json=data)

// Use a library like axios-debug-log
const axios = require('axios');

// Create axios instance with logging
const api = axios.create({
    baseURL: 'https://api.hitl.sh/v1',
    headers: {
        'Authorization': 'Bearer your_api_key'
    }
});

// Log requests and responses
api.interceptors.request.use(request => {
    console.log('Request:', request);
    return request;
});

api.interceptors.response.use(
    response => {
        console.log('Response:', response);
        return response;
    },
    error => {
        console.log('Error:', error.response);
        return Promise.reject(error);
    }
);

Getting Help

Self-Service Resources

API Status

Check if there are any ongoing service issues.

Community Forum

Ask questions and get help from the community.

Documentation

Review API documentation and examples.

GitHub Issues

Report bugs or request new features.

Contacting Support

When contacting support, please include:

Request ID (if available from response headers)
Timestamp of when the error occurred
Full error response including status code and message
Request details (endpoint, method, payload)
Your API key ID (not the actual key)

Contact Support

Email us at support@hitl.sh with your issue details.

Next Steps

Authentication Guide

Learn about API keys and security best practices.

Webhooks

Use callback URLs to receive notifications when requests complete.

Getting Started

Loops

Requests

Webhooks

Error Handling

Error Handling

Error Response Format

Error Response Fields

HTTP Status Codes

2xx Success

4xx Client Errors

5xx Server Errors

Common Error Scenarios

Validation Errors

Resource Access Errors

Authentication Errors

Error Handling Best Practices

1. Implement Retry Logic

2. Handle Rate Limits Gracefully

3. Validate Requests Client-Side

4. Log Errors for Debugging

Debugging Guide

Common Issues and Solutions

Request/Response Debugging

Getting Help

Self-Service Resources

API Status

Community Forum

Documentation

GitHub Issues

Contacting Support

Contact Support

Next Steps

Authentication Guide

Webhooks

​Error Handling

​Error Response Format

​Error Response Fields

​HTTP Status Codes

​2xx Success

​4xx Client Errors

​5xx Server Errors

​Common Error Scenarios

​Validation Errors

​Resource Access Errors

​Authentication Errors

​Error Handling Best Practices

​1. Implement Retry Logic

​2. Handle Rate Limits Gracefully

​3. Validate Requests Client-Side

​4. Log Errors for Debugging

​Debugging Guide

​Common Issues and Solutions

​Request/Response Debugging

​Getting Help

​Self-Service Resources

API Status

Community Forum

Documentation

GitHub Issues

​Contacting Support

Contact Support

​Next Steps

Authentication Guide

Webhooks

Error Handling

Error Response Format

Error Response Fields

HTTP Status Codes

2xx Success

4xx Client Errors

5xx Server Errors

Common Error Scenarios

Validation Errors

Resource Access Errors

Authentication Errors

Error Handling Best Practices

1. Implement Retry Logic

2. Handle Rate Limits Gracefully

3. Validate Requests Client-Side

4. Log Errors for Debugging

Debugging Guide

Common Issues and Solutions

Request/Response Debugging

Getting Help

Self-Service Resources

Contacting Support

Next Steps