Merge pull request #183 from maxl2287/feature/align-error-codes

`device-reachability-status` & `device-roaming-status`: Alignment of errors with Commonalities

code/API_definitions/device-reachability-status.yaml

@@ -109,15 +109,29 @@ paths:
         "401":
           $ref: "#/components/responses/Generic401"
         "403":
-          $ref: "#/components/responses/ReachabilityPermissionDenied403"
+          $ref: "#/components/responses/Generic403"
         "404":
-          $ref: "#/components/responses/ReachabilityNotFound404"
+          $ref: "#/components/responses/Generic404"
+        "405":
+          $ref: "#/components/responses/Generic405"
+        "406":
+          $ref: "#/components/responses/Generic406"
+        "415":
+          $ref: "#/components/responses/Generic415"
         "422":
-          $ref: "#/components/responses/ReachabilityUnprocessableEntity422"
+          $ref: "#/components/responses/Generic422"
+        "429":
+          $ref: "#/components/responses/Generic429"
         "500":
           $ref: "#/components/responses/Generic500"
+        "501":
+          $ref: "#/components/responses/Generic501"
+        "502":
+          $ref: "#/components/responses/Generic502"
         "503":
           $ref: "#/components/responses/Generic503"
+        "504":
+          $ref: "#/components/responses/Generic504"
 components:
   securitySchemes:
     openId:
@@ -241,12 +255,14 @@ components:
       example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
 
     RequestReachabilityStatus:
+      description: The request to retrieve the current roaming-status for the requested device.
       type: object
       properties:
         device:
           $ref: "#/components/schemas/Device"
 
     ErrorInfo:
+      description: The error object used for error-cases.
       type: object
       required:
         - status
@@ -273,24 +289,36 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 400
-            code: "INVALID_ARGUMENT"
-            message: "Client specified an invalid argument, request body or query param"
+          examples:
+            GENERIC_400_INVALID_ARGUMENT:
+              description: Invalid Argument. Generic Syntax Exception
+              value:
+                status: 400
+                code: INVALID_ARGUMENT
+                message: Client specified an invalid argument, request body or query param.
     Generic401:
-      description: Authentication problem with the client request
+      description: Unauthorized
       headers:
         x-correlator:
           $ref: '#/components/headers/x-correlator'
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 401
-            code: "UNAUTHENTICATED"
-            message: "Request not authenticated due to missing, invalid, or expired credentials"
-    ReachabilityPermissionDenied403:
+          examples:
+            GENERIC_401_UNAUTHENTICATED:
+              description: Request cannot be authenticated
+              value:
+                status: 401
+                code: UNAUTHENTICATED
+                message: Request not authenticated due to missing, invalid, or expired credentials.
+            GENERIC_401_AUTHENTICATION_REQUIRED:
+              description: New authentication is needed, authentication is no longer valid
+              value:
+                status: 401
+                code: AUTHENTICATION_REQUIRED
+                message: New authentication is required.
+    Generic403:
       description: |
         Client does not have sufficient permission.
         In addition to regular scenario of `PERMISSION_DENIED`, other scenarios may exist:
@@ -305,17 +333,19 @@ components:
           schema:
             $ref: '#/components/schemas/ErrorInfo'
           examples:
-            PermissionDenied:
+            GENERIC_403_PERMISSION_DENIED:
+              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
               value:
                 status: 403
-                code: "PERMISSION_DENIED"
-                message: "Client does not have sufficient permissions to perform this action"
-            InvalidTokenContext:
+                code: PERMISSION_DENIED
+                message: Client does not have sufficient permissions to perform this action.
+            GENERIC_403_INVALID_TOKEN_CONTEXT:
+              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
               value:
                 status: 403
                 code: INVALID_TOKEN_CONTEXT
-                message: Invalid access token context
-    ReachabilityNotFound404:
+                message: "{{field}} is not consistent with access token."
+    Generic404:
       description: Resource Not Found
       headers:
         x-correlator:
@@ -325,25 +355,65 @@ components:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           examples:
-            DeviceIdentifierNotFound:
+            NOT_FOUND:
+              value:
+                status: 404
+                code: NOT_FOUND
+                message: The specified resource is not found
+            DEVICE_IDENTIFIER_NOT_FOUND:
               value:
                 status: 404
                 code: DEVICE_NOT_FOUND
                 message: Some identifier cannot be matched to a device
-    Generic409:
-      description: Conflict
+    Generic405:
+      description: Method Not Allowed
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_405_METHOD_NOT_ALLOWED:
+              description: Invalid HTTP verb used with a given endpoint
+              value:
+                status: 405
+                code: METHOD_NOT_ALLOWED
+                message: The requested method is not allowed/supported on the target resource.
+    Generic406:
+      description: Not Acceptable
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_406_NOT_ACCEPTABLE:
+              description: API Server does not accept the media type (`Accept-*` header) indicated by API client
+              value:
+                status: 406
+                code: NOT_ACCEPTABLE
+                message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers.
+    Generic415:
+      description: Unsupported Media Type
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 409
-            code: CONFLICT
-            message: "The specified resource is in a conflict"
-    ReachabilityUnprocessableEntity422:
+          examples:
+            GENERIC_415_UNSUPPORTED_MEDIA_TYPE:
+              description: Payload format of the request is in an unsupported format by the Server. Should not happen
+              value:
+                status: 415
+                code: UNSUPPORTED_MEDIA_TYPE
+                message: The server refuses to accept the request because the payload format is in an unsupported format.
+    Generic422:
       description: Unprocessable Entity
       headers:
         x-correlator:
@@ -353,49 +423,127 @@ components:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           examples:
-            UnsupportedDeviceIdentifiers:
-              value:
-                status: 422
-                code: UNSUPPORTED_DEVICE_IDENTIFIERS
-                message: "None of the provided device identifiers is supported by the implementation"
-            InconsistentDeviceIdentifiers:
+            GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
+              description: Inconsistency between device identifiers not pointing to the same device
               value:
                 status: 422
                 code: DEVICE_IDENTIFIERS_MISMATCH
-                message: Device identifiers mismatch
-            DeviceNotSupported:
+                message: Provided device identifiers are not consistent.
+            GENERIC_422_DEVICE_NOT_APPLICABLE:
+              description: Service is not available for the provided device
               value:
                 status: 422
                 code: DEVICE_NOT_APPLICABLE
-                message: Service not applicable to the device
-            NetworkIssueToRetrieveReacabilityStatus:
+                message: The service is not available for the provided device.
+            GENERIC_422_UNABLE_TO_PROVIDE_REACHABILITY_STATUS:
               value:
                 status: 422
-                code: DEVICE_REACHABILITY_STATUS.UNABLE_TO_PROVIDE_REACHABILITY_STATUS
+                code: UNABLE_TO_PROVIDE_REACHABILITY_STATUS
                 message: Network issue - Unable to provide reachability status
+            GENERIC_422_UNSUPPORTED_DEVICE_IDENTIFIERS:
+              value:
+                status: 422
+                code: UNSUPPORTED_DEVICE_IDENTIFIERS
+                message: None of the provided device identifiers is supported by the implementation
+    Generic429:
+      description: Too Many Requests
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_429_QUOTA_EXCEEDED:
+              description: Request is rejected due to exceeding a business quota limit
+              value:
+                status: 429
+                code: QUOTA_EXCEEDED
+                message: Either out of resource quota or reaching rate limiting.
+            GENERIC_429_TOO_MANY_REQUESTS:
+              description: API Server request limit is overpassed
+              value:
+                status: 429
+                code: TOO_MANY_REQUESTS
+                message: Either out of resource quota or reaching rate limiting.
     Generic500:
-      description: Server error
+      description: Internal Server Error
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_500_INTERNAL:
+              description: Problem in Server side. Regular Server Exception
+              value:
+                status: 500
+                code: INTERNAL
+                message: Unknown server error. Typically a server bug.
+    Generic501:
+      description: Not Implemented
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 500
-            code: "INTERNAL"
-            message: "Server error"
+          examples:
+            GENERIC_501_NOT_IMPLEMENTED:
+              description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations
+              value:
+                status: 501
+                code: NOT_IMPLEMENTED
+                message: This functionality is not implemented yet.
+    Generic502:
+      description: Bad Gateway
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_502_BAD_GATEWAY:
+              description: Internal routing problem in the Server side that blocks to manage the service properly
+              value:
+                status: 502
+                code: BAD_GATEWAY
+                message: An upstream internal service cannot be reached.
     Generic503:
-      description: Service unavailable. Typically the server is down.
+      description: Service Unavailable
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
-          example:
-            status: 503
-            code: "UNAVAILABLE"
-            message: "Service unavailable"
+          examples:
+            GENERIC_503_UNAVAILABLE:
+              description: Service is not available. Temporary situation usually related to maintenance process in the server side
+              value:
+                status: 503
+                code: UNAVAILABLE
+                message: Service Unavailable.
+    Generic504:
+      description: Gateway Timeout
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            GENERIC_504_TIMEOUT:
+              description: API Server Timeout
+              value:
+                status: 504
+                code: TIMEOUT
+                message: Request timeout exceeded.