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/rest/guides/best-practices-for-integrators#dealing-with-secondary-rate-limits

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

The current text (emphasis added) says:

When you have been limited, use the Retry-After response header to slow down. The value of the Retry-After header will always be an integer, representing the number of seconds you should wait before making requests again. For example, Retry-After: 30 means you should wait 30 seconds before sending more requests.

A number of other vendors (spotify/web-api#542, WebexCommunity/WebexPythonSDK#52) have at times sent retry-after: 0 when they in fact meant retry-after: 1.

In adding some code to deal w/ that case, I decided to check the documentation, and the documentation here doesn't promise that the server won't send retry-after: -10 or retry-after: 0.

I'm glad it's promising not to send the float 1.5, the string tomorrow, or the date-time 2038-01-19T03:14:08Z.

• If it will always be > 0, it'd be nice if the documentation either promised that the value would be a positive integer, or a natural number.
• If it might be 0, it'd be nice if the documentation specified whole number and then explained what one should do when the value is 0.
• If it could be negative, the documentation should explain what one should do when that happens.

Additional information

I'm aware that this is a best practices guide.

These are really the only pages I can find that generally discuss the subject:

• Resources in the REST API (Rate limit HTTP headers)
• Getting started with the REST API
• Best practices for integrators

Of these pages, only Best practices for integrators actually talks about retry-after.

This repository used to have (non-user-facing) code that handled 429: 704f699

And it currently has:

• This comment (which would trigger a PR from my tooling for this line, but, I'm not sure if that'd be particularly welcome):
  

  docs/script/check-english-links.js

  Line 8 in ad3d0cd

  // Note that linkinator somtimes returns 429 and 503 errors for links that are not actually

• And this, which definitely isn't user facing:
  

  docs/script/check-english-links.js

  Line 32 in ad3d0cd

  const retryStatusCodes = [429, 503, 'Invalid']

It'd be great if a user facing page explicitly mentioned 429. (There's one REST API that mentions 429, but I don't know why #16682.)