h1. API Error Handling

%{color:green}This is information is currently deprecated but planned to be updated.%

For the API we want to create a more detailed error model. The error message should be machine- and human-readable, therefore we use json format as response language. 

One example could be:

<pre>
{
  title: "Forbidden",
  status: 403,
  detail: "You don't have the permission to access the requested resource. Please authenticate with the server, either through login via the user interface or token based authentication.",
  timestamp: "Fri, 29 May 2020 10:13:22 GMT",
}
</pre>

As a RFC draft for API error messages states (https://tools.ietf.org/html/draft-nottingham-http-problem-07): 

*  "title" (string) - A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localisation.
* "status" (number) - The HTTP status code ([RFC2616], Section 6) generated by the origin server for this occurrence of the problem.
* "detail" (string) - An human readable explanation specific to this occurrence of the problem.
* "instance" (string) - An absolute URI that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.
* "timestamp" (string) - The system timestamp
* "help" (string) - URI to a help site or the manual site

h1. Used Error Codes

Following error codes will be caught by the API error handler: 

|_. Code |_. Description         |_. Detail  |_. Error Message|
|400     | Bad Request           | Client sent an invalid request — such as lacking required request body or parameter | The request is invalid. The body or parameters are wrong.|
|401     | Unauthorized	         | Client failed to authenticate with the server| You failed to authenticate with the server. |
|403     | Forbidden	         | Client authenticated but does not have permission to access the requested resource | You don't have the permission to access the requested resource. Please authenticate with the server, either through login via the user interface or token based authentication. |
|404     | Not Found	         | The requested resource does not exist | Something went wrong! Maybe only digits are allowed. Please check the URL. |
|404a     | Not Found	         | The requested resource does not exist | The requested entity doesn't exist. Try another ID. |
|404b     | Not Found	         | The requested resource does not exist | The syntax is incorrect. Only digits are allowed. For further usage, please confer the help page. |
|404c     | Not Found	         | The requested resource does not exist | The syntax is incorrect. Valid codes are: actor, event, place, source, reference and object. For further usage, please confer the help page. |
|404d     | Not Found	         | The requested resource does not exist | The syntax is incorrect. These class code is not supported. For the classes please confer the model. |
|404e     | Not Found	         | The requested resource does not exist | The syntax is incorrect. Only integers between 1 and 100 are allowed. |
|404f     | Not Found	         | The requested resource does not exist | The syntax is incorrect. Only valid operators are allowed. |
|405     | Invalid Method        | The method is not available | The method used is not supported. Right now only GET is allowed.|

h1. Reference Links

* https://nordicapis.com/best-practices-api-error-handling/
* https://tools.ietf.org/html/rfc7807
* https://tools.ietf.org/html/draft-nottingham-http-problem-07
* https://flask.palletsprojects.com/en/1.1.x/patterns/apierrors/

h1. To Do:

* Refactor Error Codes?