"Create a reference" API call fails with HTTP 422 without meaningful message

从 POST /refs OpenAPI 条目和 components/responses/validation_failed 定义开始，然后将它们的 422 详细信息与 issue 中提到的 REST API 故障排查页面进行比较。相关响应文档和错误指南能够更有用地解释可能的失败情况（包括报告的引用创建案例）即表示完成。

In our publish workflows, we perform a POST /refs API call ("Create a reference") to create a new branch on the repo. Sometimes it works, sometimes it fails with HTTP 422 and message propety: 'Reference update failed'. The request data is valid, also in the cases where the HTTP 422 occurred.

Because I suspected that branch protection could have to do with it, I tried the API call with and without "Restrict pushes that create matching branches" enabled, and in a small test workflow that just created a branch, it succeeded with and without that setting enabled.

Actions log of a recent occurrence of the HTTP 422 error in one of our repos: https://github.com/zhmcclient/zhmc-log-forwarder/actions/runs/15422025589/job/43399389633

The issues with this are:

• The information "Reference update failed" provided by the message property does not provide any information about why it failed and thus is not useful at all to fix the reason for the failure. That message should be improved in the code to indicate the reason for the failure. I am aware that this repo here is the docs repo, so please forward this to the right repo or let me know where to open an issue for this.
• The OpenAPI documentation for POST /refs (and for many other API calls) refers to #/components/responses/validation_failed which is very generic and says in its description "Validation failed, or the endpoint has been spammed.". This description is not very helpful and the documentation should be improved. For example, some API calls do have a specific description for HTTP 422.
• The REST API documentation site https://docs.github.com/en/rest covers HTTP 422 to some extent, but it does not seem to cover our case, above. See below for more details.

I believe this issue applies to multiple GitHub API calls. See for example this discussion item: https://github.com/orgs/community/discussions/42272

The REST API trouble shooting section at https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api?apiVersion=2022-11-28 has some information on HTTP 422, but none of that seems to apply to the response we are getting.

I searched for "HTTP 422" in the documentation (using the search field in the above trouble shooting link) and got this response:

HTTP 422 (Unprocessable Entity) typically occurs when the server understands the request but cannot process it due to semantic errors. If you're encountering this error while using GitHub's REST API, it could be due to invalid or missing data in your request.

Here are some common causes and troubleshooting steps:

• Check the Request Body: Ensure that the JSON payload in your request is correctly formatted and includes all required fields. For example, when creating a repository, ensure fields like name are provided.
• Validate Input Data: Verify that the values you are sending match the expected data types and constraints. For instance, if you're using the /repos endpoint, ensure the repository name doesn't contain invalid characters.
• Authentication and Permissions: Confirm that your access token or authentication method has the necessary permissions for the action you're trying to perform. For example, creating a repository requires repo scope.
• Endpoint-Specific Requirements: Review the documentation for the specific endpoint you're using to ensure all required parameters are included. For example, for artifact attestations, ensure the payload matches the expected format.
• Error Message Details: The response body of the 422 error often contains details about what went wrong. Check the error message for clues about missing or invalid fields.

If you need more information about specific endpoints, you can refer to the documentation:

On "Check the error message for clues about missing or invalid fields": Unfortunately, the message property is not very helpful, as explained above. Also, this response does not even mention the case of "the endpoint has been spammed".

Searching for "what does HTTP 422 error mean in the GitHub rest api?" in the search field results in this response:

The HTTP 422 error in the GitHub REST API means "Validation failed, or the endpoint has been spammed." This typically occurs when the parameters provided in the request are invalid or do not meet the requirements of the API endpoint.

To troubleshoot this error:

• Review the documentation for the specific endpoint you are using to ensure all required parameters are included and correctly formatted.
• Check if any unique constraints (e.g., unique names for resources) are being violated.
• If the error persists, refer to the message property in the API response for more details about the issue.

For more information, see: https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api

This response at least brings up the generic OpenAPI definition for HTTP 422 and links to the troubleshooting section, but again refers to the not very helpful message property in the response, and it is also not very consistent with the first response above.

The bottom line of all this is that the documentation and the response data do not give a hint about the root cause of the HTTP 422 error, or guidance on how to handle it.