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 Response Fields
Always
true
for error responsesHuman-readable error message describing what went wrong
Additional error context, validation details, or debugging information (optional)
HTTP Status Codes
2xx Success
200 OK
200 OK
Request succeeded. Response contains the requested data.
201 Created
201 Created
Resource was created successfully.
4xx Client Errors
400 Bad Request
400 Bad Request
Request data is invalid or malformed.Common causes:Example - Missing required field:
- Missing required fields
- Invalid field values
- Malformed JSON
- Validation failures
401 Unauthorized
401 Unauthorized
403 Forbidden
403 Forbidden
Authentication is valid but access is denied.Common causes:Permission-specific error:
- Insufficient permissions
- Not the resource owner
- Account limitations
404 Not Found
404 Not Found
The requested resource doesn’t exist.Common causes:Request not found:
- Invalid resource ID
- Resource was deleted
- Typo in endpoint URL
429 Too Many Requests
429 Too Many Requests
Rate limit has been exceeded.API key rate limit:
5xx Server Errors
500 Internal Server Error
500 Internal Server Error
An unexpected error occurred on our servers.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
502 Bad Gateway
Gateway or proxy error, usually temporary.
503 Service Unavailable
503 Service Unavailable
Common Error Scenarios
Validation Errors
Request Text Too Long:Resource Access Errors
Loop Not Found:Authentication Errors
Missing API Key:Error Handling Best Practices
1. Implement Retry Logic
Use exponential backoff for transient errors:2. Handle Rate Limits Gracefully
3. Validate Requests Client-Side
Implement client-side validation to catch errors early:4. Log Errors for Debugging
Implement comprehensive error logging:Debugging Guide
Common Issues and Solutions
API Key Not Working
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
Request Validation Failing
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
Rate Limit Issues
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
Timeout Errors
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
Request/Response Debugging
Enable verbose logging to see full HTTP requests and responses: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.
Rate Limits
Understand API rate limits and optimization strategies.
Webhooks
Set up webhooks to avoid polling and reduce API calls.