GraphQL errors, and especially rate limit errors, are not documented

[FiloSottile]

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

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

There seems to be no documentation for what the GraphQL API returns on error conditions.

In particular, I can't find what error code to expect once the rate limit is exceeded. I see I can use the rateLimit query field to get information on how many points I have left when a query succeeds, but I can't rely on that alone as I might have a few points left and then make a very large request.

I assume a rate limit error will also provide a resetAt field, but I have no idea under what name or path. The only way I can see to develop an app that will handle rate limits gracefully is to burn 5000 points and hit the error to learn how it looks like.

Additional information

No response

---

Maintainer update

Proposed changes to fix this issue

Expand the Resource limitations article with examples of what happens if you exceed rate limits using the information from the comments below, in particular:

• GraphQL errors, and especially rate limit errors, are not documented #22607 (comment)
• GraphQL errors, and especially rate limit errors, are not documented #22607 (comment)

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

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

[skedwards88]

The response code will be 200, and the errors field will indicate that you have a rate error. For example:

With GitHub CLI, a rate limited response looks like:

% gh api graphql -f query='{
  viewer {
    login
    isSiteAdmin
  }
}'
{
  "errors": [
    {
      "type": "RATE_LIMITED",
      "message": "API rate limit exceeded for user ID 9961."
    }
  ]
}
gh: API rate limit exceeded for user ID 9961.

With curl, a rate limited response looks like:

curl -w "%{http_code}" https://api.github.com/graphql \
  -H "Authorization: token $GITHUB_TOKEN" \
  --compressed \
  --data-binary '{"query":"{\n\t__schema{\n queryType {\n fields{\n name\n }\n }\n }\n}"}'
{"errors":[{"type":"RATE_LIMITED","message":"API rate limit exceeded for user ID 9961."}]}
200

You or anyone else is welcome to add this info to the docs.

[FiloSottile]

Thank you. Is there a response header for the retryAt time or some other way to acquire it?

[mmrobins]

yes, there's an x-ratelimit-reset, along with some other useful headers

% curl -vvv https://api.github.com/graphql \
  -H "Authorization: token $GITHUB_TOKEN" \
  --compressed \
  --data-binary '{"query":"{\n\t__schema{\n queryType {\n fields{\n name\n }\n }\n }\n}"}' \
  2> >(grep x-ratelimit)
< x-ratelimit-limit: 5000
< x-ratelimit-remaining: 0
< x-ratelimit-reset: 1670985544
< x-ratelimit-used: 5000
< x-ratelimit-resource: graphql

[pgcd]

I'm trying to use this query to fetch a single file from my repo:

{
  repository(owner: "myorg", name: "myrepo") {
    content: object(expression: "develop:src/locale_files/de/LC_MESSAGES/django.po") {
      ... on Blob {
        text
      }
    }
  }
}

And the resulting text is truncated at 510292 - there's a flag in the result that confirms that the contents are truncated, but it would've been nice to know that in advance, instead of spending time getting this to work only to find it's completely useless.

[felicitymay]

@pgcd - you might find this article useful when you're doing future work using the GraphQL API: Resource limitations - GitHub Docs.