what api responses mean

description of api responses - tentative - some of these may not be
correct