Typed Errors and Graphene

Hi folks,

I’m raising this issue to gauge ideas from the Python community on error handling best practices.

The usual way to handle errors in GraphQL is by inspecting the top-level errors key:

{
  "errors": {
    # ... your error details ...
  },
  "data": null
}

However, this is usually problematic for API clients as they don’t know what to expect from this errors key. This means that error discoverability is impacted.

Another downside, is that the data key must be null when these high-level errors are raised. In many situations API clients are interested in calling a mutation and, even if it fails, they’d like to receive data back. This data can be anything, but it’s usually the object being mutated itself.

Another approach is extending upon this idea of typed errors that is strongly supported by Lee Byron as you can see here.

This seems to solve both problems above (along with many others). Here’s my take on what this would look like in Graphene:

class ErrorInterface(graphene.Interface):
    message = graphene.NonNull(graphene.String)


class ThingAErrorType(graphene.ObjectType):
    class Meta:
        interfaces = [ErrorInterface]


class ThingBErrorType(graphene.ObjectType):
    class Meta:
        interfaces = [ErrorInterface]


class MySweetMutationErrorUnion(graphene.Union):
    class Meta:
        types = [ThingAErrorType, ThingBErrorType]


class MySweetMutation():
    error = graphene.Field(MySweetMutationErrorUnion)
    output = graphene.Field(MySweetOutputType)

    def mutate(self, info, input):
        try:
             thing_a = do_thing_a(input)
        except ThingAException:
             return MySweetMutation(error=ThingAErrorType())
        try:
             thing_b = do_thing_b(input)
        except ThingBException:
             return MySweetMutation(error=ThingBErrorType())
        # happy path!
        output = MySweetOutputType(thing_a=thing_a, thing_b=thing_b)
        return MySweetMutation(output=output)

If we have a look at what the schema looks like, we have this:

And finally, API clients can query this mutation like this:

    mutation mySweetMutation($input: MySweetMutationInput!) {
        mySweetMutation(input: $input) {
            output {
                # ....
            }
            error {
                ... on ThingAError {
                    __typename
                    message
                }
                ... on ThingBError {
                    __typename
                    message
                }
                 # We have an interface here so that we
                 # can extend the union with more errors without breaking
                 # backwards compatibility!!
                 __typename
                 message
            }
        }
    }

I’m interested in your thoughts in this approach. Thanks!

[marcelofern]

@erikwrede

Absolutely, no worries at all. If you want my help clarifying anything just let me know. Cheers!

[erikwrede]

@marcelofern Sorry for the long wait! I’ve got more clarity on docs now. Working on getting the docs hosted on github pages. That process will not negatively affect any ongoing documentation work. Feel free to PR your suggested documentation!

Keep in mind: I want to add doctest to the docs, to prevent PRs from invalidating any of the docs in the future. It would be awesome if your PR already contained doctests so we could have a clean start.

Additionally, we have decided to integrate the typed errors into graphene as a an optional feature in the Mutation base class. Are you interested in helping? 🙂