Add error handling section.

Co-authored-by: Ted Thibodeau Jr <[email protected]> Co-authored-by: Manu Sporny <[email protected]>
w3c-ccg · Jun 18, 2024 · 494f0a2 · 494f0a2
1 parent b622a3c
commit 494f0a2
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 50 deletions.
diff --git a/holder.yml b/holder.yml
@@ -45,10 +45,6 @@ paths:
           description: Gone! There is no data here
         "418":
           description: I'm a teapot - MUST not be returned outside of pre-arranged scenarios between both parties
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
     delete:
       tags:
        - Credentials
@@ -72,10 +68,6 @@ paths:
           description: Credential not found
         "410":
           description: Gone! There is no data here
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
   /credentials:
     get:
       tags:
@@ -113,10 +105,6 @@ paths:
           description: Not Authorized
         "410":
           description: Gone! There is no data here
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
   /credentials/derive:
     post:
       tags:
@@ -144,10 +132,6 @@ paths:
                 $ref: "#/components/schemas/DeriveCredentialResponse"
         "400":
           description: Invalid Request
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
 
   /presentations/{id}:
     get:
@@ -179,10 +163,6 @@ paths:
           description: Presentation not found
         "410":
           description: Gone! There is no data here
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
     delete:
       tags:
        - Presentations
@@ -206,10 +186,6 @@ paths:
           description: Presentation not found
         "410":
           description: Gone! There is no data here
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
   /presentations:
     get:
       tags:
@@ -247,10 +223,6 @@ paths:
           description: Not Authorized
         "410":
           description: Gone! There is no data here
-        "500":
-          description: Internal Error
-        "501":
-          description: Not Implemented
     post:
       summary: Creates a presentation and returns it in the response body.
       tags:
@@ -277,8 +249,6 @@ paths:
                 $ref: "#/components/schemas/CreatePresentationResponse"
         "400":
           description: invalid input!
-        "500":
-          description: error!
   /exchanges:
     get:
       summary: Provides a discovery endpoint for the exchanges supported by this server endpoint.
@@ -385,8 +355,6 @@ paths:
                 }
         "400":
           description: invalid input
-        "500" :
-          description: error
 
   /exchanges/{exchange-id}:
     post:
@@ -434,10 +402,6 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-        "501":
-          description: Service not implemented.
-        "500":
-          description: Internal server error.
   /exchanges/{exchange-id}/{transaction-id}:
     post:
       summary: Receives information related to an existing exchange.
@@ -480,10 +444,6 @@ paths:
                 $ref: "#/components/schemas/ErrorResponse"
         "404":
           description: The associated exchange or transaction was not found.
-        "500":
-          description: Internal server error.
-        "501":
-          description: Service not implemented.
 
 components:
   securitySchemes:

diff --git a/index.html b/index.html
@@ -464,6 +464,7 @@ <h3>Storage Services</h3>
             (Verifier) &bull; Storage Service (Holder)
           </strong>
         </p>
+      </section>
       <section>
         <h3>Workflow Service</h3>
         <p>
@@ -1233,6 +1234,65 @@ <h4>Exchange Examples</h4>
       </section>
     </section>
 
+    <section>
+      <h3>Error Handling</h3>
+      <p>
+        Error handling and messaging in the VC-API aligns with Problem Details for HTTP APIs [[RFC9457]]. 
+        Implementers SHOULD include a status and a title in the error response body 
+        relating to the specifics of the endpoint on which the error occurs. 
+      <p>
+      <p>
+        Aligning on error handling and messaging will greatly improve test-suites accuracy 
+        when identifying technical friction impacting interoperability.
+      </p>
+      </p>
+        Leveraging other fields such as detail, instance and type is encouraged, 
+        to provide more contextual feedback about the error, 
+        while being conscious of security concerns and hence not disclosing sensitive information.
+      </p>
+      <p>
+        Implementers should handle all server errors to the best of their capabilities. 
+        Endpoints should avoid returning improperly handled 500 errors in production 
+        environments, as these may lead to information disclosure.
+      </p>
+      <h4>Relationship between verification, validation and error handling</h4>
+      <p>
+        It is recommended to avoid raising errors while performing verification, 
+        and instead gather ProblemDetails objects to include in the verification results.
+      </p>
+      <h4>Types of ProblemDetails</h4>
+        An implementer can refer to the [[VC-DATA-MODEL-2.0]] and the [[VC-BITSTRING-STATUS-LIST]] for currently defined ProblemDetails types.
+        <pre class="example"
+          title="ProblemDetails">
+          {
+            "type": "https://www.w3.org/TR/vc-data-model#CRYPTOGRAPHIC_SECURITY_ERROR",
+            "status": 400,
+            "title": "CRYPTOGRAPHIC_SECURITY_ERROR",
+            "detail": "The cryptographic security mechanism couldn't be verified. This is likely due to a malformed proof or an invalid verificationMethod."
+          }
+        </pre>
+      <h4>Verification Response</h4>
+        <h5>Errors and Warnings</h5>
+        Errors are `ProblemDetails` relating to cryptography, data model and malformed context.
+        Warnings are `ProblemDetails` relating to statuses and validity periods.
+
+        The `VerificationResponse` object MUST have the `verified` value set to `false` if an error is included.
+        The `VerificationResponse` object MUST have the `verified` value set to `true` if no errors are included.
+
+        <pre class="example"
+          title="Verification Response">
+          {
+            "verified": false,
+            "document": verifiableCredential,
+            "mediaType": "application/vc",
+            "controller": issuer,
+            "controllerDocument": didDocument,
+            "warnings": [ProblemDetails],
+            "errors": [ProblemDetails]
+          }
+        </pre>
+    </section>
+
   </section>
 
   <section class="appendix">

diff --git a/issuer.yml b/issuer.yml
@@ -43,8 +43,6 @@ paths:
             The request could not be processed due to one of the following reasons:
                         - The provided value of 'issuer' does not match the expected configuration.
                         - Another condition that results in a Bad Request.
-        "500":
-          description: error!
   /credentials/status:
     post:
       summary: Updates the status of an issued credential
@@ -70,8 +68,6 @@ paths:
           description: Bad Request
         "404":
           description: Credential not found
-        "500":
-          description: Internal Server Error
 components:
   securitySchemes:
     $ref: "./components/SecuritySchemes.yml#/components/securitySchemes"

diff --git a/verifier.yml b/verifier.yml
@@ -40,8 +40,6 @@ paths:
                 $ref: "#/components/schemas/VerifyCredentialResponse"
         "400":
           description: invalid input!
-        "500":
-          description: error!
   /presentations/verify:
     post:
       summary: Verifies a Presentation with or without proofs attached and returns a verificationResult in the response body.
@@ -75,8 +73,6 @@ paths:
           description: Payload too large
         "429":
           description: Request rate limit exceeded.
-        "500":
-          description: Internal Server Error
   /challenges:
     post:
       summary: Passing an empty body to this endpoint creates and returns a challenge string in the response body.
@@ -96,8 +92,6 @@ paths:
                 $ref: "#/components/schemas/CreateChallengeResponse"
         "400":
           description: Invalid or malformed input
-        "500":
-          description: Internal server error
 components:
   securitySchemes:
     $ref: "./components/SecuritySchemes.yml#/components/securitySchemes"