Improve Error Response in APIs

[louischan-oursky]

We shall improve the error response at once, currently, there are several problems:

1. name is type of error which is confusing.
2. code is just HTTP status code, which doesn't have to be in JSON response.
3. info doesn't have standardized fields or documentation.

So instead of:

"error": {
    "name": "Invalid",
    "reason": "InvariantViolated",
    "message": "identity already exists",
    "code": 400,
    "info": {
      "cause": {
        "kind": "DuplicatedIdentity"
      }
    }
}

We shall change to:

"error": {
  "type": "TypeOfError"
  "code": "Short String for the Error"
  "message": "Human readable message"
  "info": { }
}

The main changes from the current design are:

• Use type instead of name for the category of error. Using name as type is very confusing. We also should have a list of type possible values.
• HTTP status code should go back to HTTP response header
• code and message are the actual error
• We shall study the APIs used this error scheme, and try to come up with a standardized object for info, otherwise it is not usable at all (or else we need to write a spec to indicate what error will have which info, but it is not as good as a standardized object.

Original rename suggested by Louis

• DuplicatedIdentity becomes its own error
• IdentityModifyDisabled becomes its own error
• NoAuthenticator becomes its own error
• MismatchedUser becomes its own error
• Keep ErrClaimNotVerifiable unchanged.

[linear[bot]]

DEV-1501 Rename some important errors

[chpapa]

I think we shall improve the error response at once, currently there are several problems:

1. name is type of error which is confusing.
2. code is just HTTP status code, which doesn't have to be in JSON response.
3. info doesn't have a standardized fields or documentations.

So...

1. Besides this API and Authflow, where is it being used?
2. I think instead of:

"error": {
    "name": "Invalid",
    "reason": "InvariantViolated",
    "message": "identity already exists",
    "code": 400,
    "info": {
      "cause": {
        "kind": "DuplicatedIdentity"
      }
    }
}

We shall change to:

"error": {
  "type": "TypeOfError"
  "code": "Short String for the Error"
  "message": "Human readable message"
  "info": { }
}

The main changes from current design are:

• Use type instead of name for category of error. Name is very confusing. We also should have a list of type possible values.
• HTTP status code should go back to HTTP response header
• code and message are the actual error
• We shall study the APIs used this error scheme, and try to come up with a standardized object for info, otherwise it is not usable at all (or else we need to write a spec to indicate what error will have which info, but it is not as good as a standardized object.

[chpapa]

@louischan-oursky I think part of the requirements of a good error handling is actually enable @buildbro able to write an "Error" page under https://docs.authgear.com/reference/apis

[louischan-oursky]

Use type instead of name for category of error. Name is very confusing. We also should have a list of type possible values.

The SDK is an existing consumer of the error object. We cannot just rename it. The best we can do is to repeat name as type, but we probably cannot remove name.

HTTP status code should go back to HTTP response header

The HTTP response header has the same status code. Again we cannot remove the field.

code and message are the actual error

Your proposed code is the original reason. message are the same, human-readable message. code is already taken, and we cannot remove it.

We shall study the APIs used this error scheme, and try to come up with a standardized object for info, otherwise it is not usable at all (or else we need to write a spec to indicate what error will have which info, but it is not as good as a standardized object.

The info is supposed to contain error specific information. If the error object has no specific information, then it has no info.