NGSIv2 error generation rules

[fgalan]

NGSIv2 error reporting is as follows:

(<HTTP code> - <HTTP error text> { "error": "<payload error text>", ... })

• JSON payload error (pe. the JSON misses a ;, or }, etc.): 400 - Bad Request {"error": "ParseError", ...}
• Request error which only depend on the request itself (i.e. they don't depend on the CB state), either in the URL parameters (e.g. coords format is invalid) or in the payload (note1) (e.g. a id is missing in a create entity operation): 400 - Bad Request {"error": "BadRequest, ... }
• Ambiguety due to the request may refer to several resources, e.g. updating an entity providing only its ID with several entities existing in the DB with the same ID (but different types). 409 - Conflict {"error": "TooManyResults", ...}
• The resource identified by the request (e.g. entity, subscription) is not found: 404 - Not Found {"error": "NotFound", ...}
• Errors due to the request + state combination but not exclusively from the request (e.g. POST with op=append on an existing attribute) (note2): 422 - Unprocessable Entity {"error": "Unprocesable", ...}
• HTTP layer errors
  • 411 - Length Required {"error": "LengthRequired", ... }
  • 413 - Unsupported Media Type {"error": "RequestEntityTooLarge", ... }
  • 415 - Payload Too Large {"error": "UnsupportedMediaType", ... }
  • Maybe other may arose (e.g. Method Not Allowed), but they are quite straighforward as they derive from the standard HTTP protocol operation.

Note1: Except the ones due to JSON parser error, already considered in the previous bullet.
Note2: Except the request + status conditions that lead to 404 or 409 errors described in the previous bullets.

This issue will be open while NGSIv2 is still on development, in order to check at the end that all the error match the above rules. In additon, the Error Responses in the .apib document should be edited consecuently.

[fgalan]

The description in the issue body has been adapted and include in NGSIv2 specification in PR #3226