-TBD-

How do I document the HTTP error codes in my service description?

My service relies on the standard HTTP error codes. Is there a need to document them in the service description?

The Examples/Notes section of requirement SWIM-SERV-220 Service behaviour explains that error messages and error handling in general can be included in a model view (as part of SWIM-SERV-330 Model view). They are modelled as part of the detailed service behaviour.

However, it is possible to add an entry in the service behaviour section of a service description. For example:

The following HTTP status codes, with the meaning explained in the context of the service, are used by the service operations:

400 Bad Request: Indicated for malformed requests on the part of the client.

401 Unauthorized: Indicated for authentication errors (e.g. the authentication is not provided, the credentials used do not exists, the authentication mechanism used is not valid…).

403 Forbidden: Indicated for authorization errors (e.g. the authenticated credentials are not allowed to perform this operation on the resource).

404 Not Found: The requested resource cannot be found (e.g. the <subscription_id> does not exist).

405 Method Not Allowed: The HTTP method used is not supported by the resource.

500 Internal Server Error: Catch-all error for unexpected internal errors during the processing of the request.