Error Handling

​

Error Response Format

{
  "status": 404,
  "message": "requested entity not found"
}

• status - HTTP status code as an integer
• message - Human-readable error description

​

HTTP Status Codes

​

Success Codes

​

Client Error Codes

​

Server Error Codes

​

Common Error Scenarios

​

Bad Request (400)

• Invalid UUID format
• Missing required fields
• Invalid field types
• Validation constraints not met

{
  "status": 400,
  "message": "name cannot be empty"
}

{
  "status": 400,
  "message": "invalid endpoint URL format"
}

​

Unauthorized (401)

• Missing Authorization header
• Invalid token format
• Expired token
• Revoked token

{
  "status": 401,
  "message": "Invalid token"
}

{
  "status": 401,
  "message": "Token has expired"
}

​

Forbidden (403)

• Tier limits exceeded
• Insufficient permissions
• Resource belongs to another user
• Managed runner access without Pro/Plus tier

{
  "status": 403,
  "message": "Runner limit exceeded for your tier"
}

{
  "status": 403,
  "message": "Managed runners require Pro or Plus tier"
}

​

Not Found (404)

• Invalid resource ID
• Resource deleted
• Resource belongs to different user

{
  "status": 404,
  "message": "requested entity not found"
}

​

Rate Limited (429)

• Limit: 40 requests per 10 seconds
• Cooldown: 10 seconds
• Identifier: IP address

{
  "status": 429,
  "message": "Rate limit exceeded"
}

​

Internal Server Error (500)

• Retry the request after a brief delay
• Check API status page
• Contact support if issue persists

{
  "status": 500,
  "message": "An unexpected error occurred"
}

​

Validation Errors

{
  "status": 400,
  "message": "name must be between 1 and 100 characters"
}

{
  "status": 400,
  "message": "endpoint must be a valid HTTP or HTTPS URL"
}

{
  "status": 400,
  "message": "maximum 10 tags allowed"
}

{
  "status": 400,
  "message": "file size exceeds maximum limit of 50MB"
}

​

Workflow-Specific Errors

{
  "status": 400,
  "message": "invalid workflow JSON structure"
}

{
  "status": 400,
  "message": "no runner available with matching tags"
}

• error_node - The ComfyUI node that failed
• exception_type - Type of exception
• exception_message - Detailed error message

​

Need Help?

1. Check this documentation for common solutions
2. Verify your authentication token is valid
3. Ensure you’re within rate limits
4. Review the API Reference for correct usage
5. Contact support at support@comfycontrol.app with:
   • Request ID (if provided)
   • Timestamp of the error
   • Full error message
   • Steps to reproduce