Merge pull request #61 from coinbase/patrick/error-description

Error Descriptions
coinbase · Oct 19, 2020 · aa6665e · aa6665e
2 parents 5d91fdf + 377d42f
commit aa6665e
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 0 deletions.
diff --git a/api.json b/api.json
@@ -2004,6 +2004,11 @@
            "type":"string",
            "example":"Invalid account format"
           },
+         "description": {
+           "description":"Description allows the implementer to optionally provide additional information about an error. In many cases, the content of this field will be a copy-and-paste from existing developer documentation. Description can ONLY be populated with generic information about a particular type of error. It MUST NOT be populated with information about a particular instantiation of an error (use `details` for this). Whereas the content of Error.Message should stay stable across releases, the content of Error.Description will likely change across releases (as implementers improve error documentation). For this reason, the content in this field is not part of any type assertion (unlike Error.Message).",
+           "type":"string",
+           "example":"This error is returned when the requested AccountIdentifier is improperly formatted."
+          },
          "retriable": {
            "description":"An error is retriable if the same request may succeed if submitted again.",
            "type":"boolean"

diff --git a/models/Error.yaml b/models/Error.yaml
@@ -42,6 +42,22 @@ properties:
       the details field.
     type: string
     example: "Invalid account format"
+  description:
+    description: |
+      Description allows the implementer to optionally provide additional information
+      about an error. In many cases, the content of this field will be a copy-and-paste
+      from existing developer documentation.
+
+      Description can ONLY be populated with generic information about a particular
+      type of error. It MUST NOT be populated with information about a particular
+      instantiation of an error (use `details` for this).
+
+      Whereas the content of Error.Message should stay stable across releases, the
+      content of Error.Description will likely change across releases (as implementers
+      improve error documentation). For this reason, the content in this field
+      is not part of any type assertion (unlike Error.Message).
+    type: string
+    example: "This error is returned when the requested AccountIdentifier is improperly formatted."
   retriable:
     description: |
       An error is retriable if the same request may succeed if submitted