Documenting error responses of REST API

[stmllr]

What article on docs.github.com is affected?

Basically any REST API endpoint which returns HTTP 4xx responses

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

The REST API documentation provides in depth description of responses for successful requests.
However things might not work as expected and then the API responds with HTTP errors. Some of them are predictable (4xx), some not (5xx).
For example, fetching a repository which is affected by DMCA takedown notice ends up with HTTP 451 Unavailable for Legal Reasons

Additional information

As GitHub App developer I would love to have predictable errors as part of the documentation
In order to gracefully handle some errors
When developing GitHub apps which consume REST API

Currently I create pull requests for octokit.rb whenever I identify a type of error which I need to handle. Having the errors documented would make this job much easier.

[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.

[janiceilene]

Thanks for letting us know @stmllr ⚡ The @github/docs-content-ecosystem will take a look at this issue!

[simpsoka]

Thanks for opening this @stmllr! @imwiss and I have been chatting about improving some of the metadata around these responses, which would help us provide a better output in the documentation. I'd love to talk with you about that project and get your feedback -- would be curious to keep talking with you about that project if you're interested?

[stmllr]

sure @simpsoka

[rachmari]

@stmllr thanks for opening this up! I agree that it'd be great to make the possible HTTP error codes accessible. In addition to the conversation @simpsoka has started I've created an issue to see if we can collect this information in the public GitHub OpenAPI description.

I'll keep you updated on that discussion! ⚡

[zaradam]

Bu sayıyı açtığınız için teşekkürler. Bir GitHub dokümanlar ekibi üyesi yakında geri bildirimde bulunmalıdır. Bu arada, lütfen katkıda bulunma kurallarına göz atın .

Ok

[zaradam]

Ok