Documenting error responses of GraphQL API

[laymonage]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/graphql/reference

What part(s) of the article would you like to see updated?

GraphQL API always returns HTTP 200 OK status code in the response, so we have to rely on the response data in order to handle errors. Unfortunately, the GraphQL API documentation does not have any information on the types of possible errors. It's not in the GraphQL API schema as well, so the only way to know would be to stumble upon the error yourself and learn the hard way.

Additional information

As a GitHub App developer, predictable errors are always preferable so that we can handle them gracefully.

It would be great if there's a dedicated section for GraphQL API error responses. It should document at least the following errors:

• Unauthorized errors (bad credentials). AFAIK this uses exactly the same format as the REST API, i.e.

  {
    "message": "Bad credentials",
    "documentation_url": "https://docs.github.com/graphql"
  }

• Rate limit errors. Unlike the REST API that uses the following format:

  {
    "message": "API rate limit exceeded for X.X.X.X. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
    "documentation_url": "https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"
  }

  The GraphQL API uses the following format:

  {
    "errors": [
      {
        "type": "RATE_LIMITED",
        "message": "API rate limit exceeded for installation ID 12345678."
      }
    ]
  }

• GraphQL API schema errors, for example:

  {
    "errors": [
      {
        "path": [
          "query",
          "viewer",
          "repositories",
          "first"
        ],
        "extensions": {
          "code": "argumentLiteralsIncompatible",
          "typeName": "Field",
          "argumentName": "first"
        },
        "locations": [
          {
            "line": 9,
            "column": 5
          }
        ],
        "message": "Argument 'first' on Field 'repositories' has an invalid value (\"hello\").   Expected type 'Int'."
      }
    ]
  }

This is somewhat related to #194.

[ramyaparimi]

@laymonage
Thanks so much for opening an issue! I'll triage this for the team to take a look 👀

[docubot]

Thank you for opening this issue! Updates to the REST/GraphQL API description must be made internally. I have copied your issue to an internal issue, so I will close this issue.