Improve error handling code

[miparnisari]

Checklist

• I agree to the terms within the OpenFGA Code of Conduct.

Describe the problem you'd like to have solved

Design concern in our codebase: if an API call bubbles up an error that isn't understood by our mapping layer (

openfga/pkg/server/errors/encoded_errors.go

Line 69 in ab0d835

func NewEncodedError(errorCode int32, message string) *EncodedError {

) we default to throwing HTTP 500, which is non-ideal: (the SDKs will automatically retry, it can trigger alarms, etc).

See some occurrences of this problem:

• HandleTupleValidateError throw 500 errors when condition is invalid  #1419
• fix: in write API, if auth model ID not found, throw 400 instead of 500 error #725
• fix: storage conflict errors return 409 instead of 500 #1179

Describe the ideal solution

A suggested pattern by folks at Okta is:

• Define top level errors that represent common error categories
• Inside domain/internal packages, canonicalize all package specific errors into those top level errors.
• Domain packages should know how to canonicalize those top level errors into package-specific errors when necessary, like in the case of a grpc server

This is a suggestion, we can do some discovery around what would work best works for us given that, ideally, error handling between OpenFGA and Okta FGA is consistent. Whatever we do, we need team buy-in.

Alternatives and current workarounds

No response

Additional context

No response