some comments for discussion
added some comments to the specs
simplified and aligned error classes and added more annotations. all
errors return 400 HTTP status code