Open louischan-oursky opened 3 months ago
I think we shall improve the error response at once, currently there are several problems:
name
is type of error which is confusing. code
is just HTTP status code, which doesn't have to be in JSON response.info
doesn't have a standardized fields or documentations.So...
"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:
type
instead of name
for category of error. Name is very confusing. We also should have a list of type
possible values.code
and message
are the actual errorinfo
, 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.@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
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.
We shall improve the error response at once, currently, there are several problems:
name
is type of error which is confusing.code
is just HTTP status code, which doesn't have to be in JSON response.info
doesn't have standardized fields or documentation.So instead of:
We shall change to:
The main changes from the current design are:
type
instead ofname
for the category of error. Usingname
astype
is very confusing. We also should have a list oftype
possible values.code
andmessage
are the actual errorinfo
, otherwise it is not usable at all (or else we need to write a spec to indicate what error will have whichinfo
, but it is not as good as a standardized object.Original rename suggested by Louis