feat!: make error code an enum and include optional error message

specification.json

@@ -138,7 +138,7 @@
         {
             "id": "Requirement 1.4.7",
             "machine_id": "requirement_1_4_7",
-            "content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain a string identifying an error occurred during flag evaluation and the nature of the error.",
+            "content": "In cases of abnormal execution, the `evaluation details` structure's `error code` field MUST contain an `error code`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -170,6 +170,13 @@
             "RFC 2119 keyword": "SHOULD",
             "children": []
         },
+        {
+            "id": "Requirement 1.4.12",
+            "machine_id": "requirement_1_4_12",
+            "content": "In cases of abnormal execution, the `evaluation details` structure's `error message` field MAY contain a string containing additional details about the nature of the error.",
+            "RFC 2119 keyword": "MAY",
+            "children": []
+        },
         {
             "id": "Requirement 1.5.1",
             "machine_id": "requirement_1_5_1",
@@ -237,7 +244,7 @@
         {
             "id": "Requirement 2.8",
             "machine_id": "requirement_2_8",
-            "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated error code having possible values `\"PROVIDER_NOT_READY\"`, `\"FLAG_NOT_FOUND\"`, `\"PARSE_ERROR\"`, `\"TYPE_MISMATCH\"`, or `\"GENERAL\"`.",
+            "content": "In cases of abnormal execution, the `provider` MUST indicate an error using the idioms of the implementation language, with an associated `error code` and optional associated `error message`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -263,6 +270,20 @@
             "RFC 2119 keyword": "MUST",
             "children": []
         },
+        {
+            "id": "Requirement 2.11",
+            "machine_id": "requirement_2_11",
+            "content": "In cases of normal execution, the `provider` MUST NOT populate the `flag resolution` structure's `error message` field, or otherwise must populate it with a null or falsy value.",
+            "RFC 2119 keyword": "MUST NOT",
+            "children": []
+        },
+        {
+            "id": "Requirement 2.12",
+            "machine_id": "requirement_2_12",
+            "content": "In cases of abnormal execution, the `evaluation details` structure's `error message` field MAY contain a string containing additional detail about the nature of the error.",
+            "RFC 2119 keyword": "MAY",
+            "children": []
+        },
         {
             "id": "Requirement 3.1.1",
             "machine_id": "requirement_3_1_1",

specification/sections/01-flag-evaluation.md

@@ -185,9 +185,9 @@ FlagEvaluationDetails<MyStruct> myStructDetails = client.getObjectDetails<MyStru
 
 ##### Requirement 1.4.7
 
-> In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain a string identifying an error occurred during flag evaluation and the nature of the error.
+> In cases of abnormal execution, the `evaluation details` structure's `error code` field **MUST** contain an `error code`.
 
-Some example error codes include: `"TARGETING_KEY_MISSING"`, `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, or `"GENERAL"`.
+See [error code](../types.md#error-code) for details.
 
 ##### Requirement 1.4.8
 
@@ -211,6 +211,10 @@ Implementations may define a standard logging interface that can be supplied as
 
 It's recommended to provide non-blocking mechanisms for flag evaluation, particularly in languages or environments wherein there's a single thread of execution.
 
+##### Requirement 1.4.12
+
+> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional details about the nature of the error.
+
 #### Evaluation Options
 
 ##### Requirement 1.5.1

specification/sections/02-providers.md

@@ -85,10 +85,17 @@ As indicated in the definition of the [`flag resolution`](../types.md#resolution
 
 ##### Requirement 2.8
 
-> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated error code having possible values `"PROVIDER_NOT_READY"`, `"FLAG_NOT_FOUND"`, `"PARSE_ERROR"`, `"TYPE_MISMATCH"`, or `"GENERAL"`.
+> In cases of abnormal execution, the `provider` **MUST** indicate an error using the idioms of the implementation language, with an associated `error code` and optional associated `error message`.
 
 The provider might throw an exception, return an error, or populate the `error code` object on the returned `flag resolution` structure to indicate a problem during flag value resolution.
 
+See [error code](../types.md#error-code) for details.
+
+```typescript
+// example throwing an exception with an error code and optional error message.
+throw new ProviderError(ErrorCode.INVALID_CONTEXT, "The 'foo' attribute must be a string.");
+```
+
 ##### Condition 2.9
 
 > The implementation language supports generics (or an equivalent feature).
@@ -133,3 +140,11 @@ class MyProvider implements Provider {
   //...
 }
 ```
+
+#### Requirement 2.11
+
+> In cases of normal execution, the `provider` **MUST NOT** populate the `flag resolution` structure's `error message` field, or otherwise must populate it with a null or falsy value.
+
+#### Requirement 2.12
+
+> In cases of abnormal execution, the `evaluation details` structure's `error message` field **MAY** contain a string containing additional detail about the nature of the error.

specification/types.md

@@ -36,7 +36,8 @@ A structure representing the result of the [flag evaluation process](./glossary.
 
 - flag key (string, required)
 - value (boolean | string | number | structure, required)
-- error code (string, optional)
+- error code ([error code](#error-code), optional)
+- error message (string, optional)
 - reason (string, optional)
 - variant (string, optional)
 
@@ -45,7 +46,8 @@ A structure representing the result of the [flag evaluation process](./glossary.
 A structure which contains a subset of the fields defined in the `evaluation details`, representing the result of the provider's [flag resolution process](./glossary.md#resolving-flag-values), including:
 
 - value (boolean | string | number | structure, required)
-- error code (string, optional)
+- error code ([error code](#error-code), optional)
+- error message (string, optional)
 - reason (string, optional)
 - variant (string, optional)
 
@@ -62,6 +64,20 @@ A set of pre-defined reasons is enumerated below:
 
 > NOTE: The `resolution details` structure is not exposed to the Application Author. It defines the data which Provider Authors must return when resolving the value of flags.
 
+### Error Code
+
+An enumerated error code represented idiomatically in the implementation language.
+
+| Error Code            | Explanation                                                                                 |
+|-----------------------|---------------------------------------------------------------------------------------------|
+| PROVIDER_NOT_READY    | The value was resolved before the provider was ready.                                       |
+| FLAG_NOT_FOUND        | The flag could not be found.                                                                |
+| PARSE_ERROR           | An error was encountered parsing data, such as a flag configuration.                        |
+| TYPE_MISMATCH         | The type of the flag value does not match the expected type.                                |
+| TARGETING_KEY_MISSING | The provider requires a targeting key and one was not provided in the `evaluation context`. |
+| INVALID_CONTEXT       | The `evaluation context` does not meet provider requirements.                               |
+| GENERAL               | The error was for a reason not enumerated above.                                            |
+
 ### Evaluation Options
 
 A structure containing the following fields: