Using ESUS' data flow diagram, develop specific API errors to return to a client

[mattrbianchi]

Summary

Now that we have a flow diagram for how client's requests will be handled, we can develop an initial set of errors at the points identified where faults can occur. This document will contain that error's code along with a specific message and any other data found necessary to return to the client by the developer.

Motivation

As clients integrate with the service, having the specific errors documented with additional context and suggestions for how to resolve them will reduce pain points.

[david-waltermire]

Note: A start of this exists in the OpenAPI defintion in PR #17. Specific error codes have been identified that address some failure modes. These definitions should be updated based on the result of this discussion.

[david-waltermire]

This is a generalized summary of the error codes used in PR #17.

Error Code	Post	Put	Get	Description
200	X	X	X	Success on POST/PUT/GET
400	X	X		Malformed/invalid request
401	X	X	X	The action requires authorization and the client is not authenticated
403	X	X	X	The action requires authorization and the client is not authorized to perform this action
404	X	X	X	The resource was not found or does not exist

A 404 has different meaning depending on the action. For example:

• Posting a CVE record to an unreserved CVE would result in a 404.
• Updating a CVE record using a PUT that was never initial submitted using a POST would result in a 404
• Retrieving a CVE record using a GET that was never initial submitted using a POST would result in a 404

A 404 is different than the user not having access, a 403. A 403 will result from an attempt to POST or PUT a CVE record that the organization has not been allocated a CVE ID for, or a PUT to an ADP container for which they do not have access.

Thoughts?