[RFC] Standard Error Codes

rfc-gql-error.md

This RFC is an attempt to identify and standardize error codes for GraphQL errors. This has bee previously discussed, and some great work and ideas came out of it. Follow the previous discussion here - #698

Why standard error codes ?

Errors ( error codes ) are the silent guardians in the programming world. Though no one wants them in their code, they actually teach us a lot and mold our thinking process. This is especially true for statically typed compiled languages like c, rust etc, where the compiler scolds and guides the programmer to fix the program's syntax. A few strong argument for having a standard set of error codes for GraphQL can be -

1. A well documented set of errors would help developers get a better understanding of the issues and errors during development.
2. Potential suggestions to fix these errors would help developer productivity too.
3. As the spec matures, this would force holistic system thinking and help catch outliers and potential issues. A good amount of effort is being put into creating comparability test suite for the GraphQL spec. This would supplement this effort too.
4. Further fine grained detailed can be encoded into the error codes, which would help the community and other implementations. Things like error severity, warning, etc, can be encoded in the error codes too.

Proposal

This proposal puts forward the intent to add code key to the standard errors spec in GraphQL. A sample implementation for the same is attached along with a sample output -

"errors": [ { "message": "Query root type must be provided.", "code": "GQ0001" } ]

Sample code to achieve this - https://github.com/shobhitchittora/graphql-js/commit/4fdfa74cbfbbcc01c2316a49ec1b6f1c94987e7c

A mapping of all the identified and important errors codes would be kept in a config ( possibly a js module of json file ) like -

const MESSAGE_DETAILS = {
  'Query root type must be provided.': {
    code: 'GQ0001'
  }, 
  ...
}

A very simple implementation would list codes in sequence, with numeric incremented codes( like GQ0009, GQ0010, and so on ). Further fine grained details like, error severity, type of error and mapping to parts of spec can encoded too.

The idea here is to have a listing of error messages and codes for the below phases of the runtime - Parse, Validate and Execute.

Current status quo in other runtimes / frameworks

Some reference in the open where errors have status codes associated for better understanding and traceability.

• React error codes -> https://github.com/facebook/react/blob/master/scripts/error-codes/codes.json
• Rust lang -> https://doc.rust-lang.org/error-index.html
• TypeScript -> https://github.com/microsoft/TypeScript/blob/master/src/compiler/diagnosticMessages.json

Ref - graphql/graphql-spec#708