错误处理¶

AtomGit API 按请求上下文返回不同的状态码。错误响应体是 JSON，message 字段说明原因；401 的响应体形如：

{
  "message": "401 Unauthorized"
}

排查时先看状态码分类：4xx 是请求本身的问题（参数、认证、权限、资源不存在），改请求才能通过；5xx 是服务端问题，可以重试。

请求类型与预期结果¶

请求类型	描述
`GET`	访问一个或多个资源并以 JSON 形式返回结果
`POST`	如果资源成功创建，则返回 `201 Created` 并以 JSON 形式返回新创建的资源
`GET` / `PUT`	如果资源被成功访问或修改，则返回 `200 OK`，返回的（修改后的）结果以 JSON 形式返回
`DELETE`	如果资源成功删除，则返回 `204 No Content`；如果资源计划被删除，则返回 `202 Accepted`

返回值	描述
`200 OK`	`GET`、`PUT` 或 `DELETE` 请求成功，并且资源本身以 JSON 形式返回
`201 Created`	`POST` 请求成功，并且资源以 JSON 形式返回
`202 Accepted`	`GET`、`PUT` 或 `DELETE` 请求成功，并且资源计划进行处理
`204 No Content`	服务器已成功满足请求，并且在响应负载体中没有额外的内容发送
`301 Moved Permanently`	资源已被定位到由 `Location` 头给出的 URL
`304 Not Modified`	资源自上次请求以来未被修改
`400 Bad Request`	API 请求的必需属性缺失，例如未给出问题的标题
`401 Unauthorized`	用户未经认证，需要有效的用户令牌
`403 Forbidden`	请求不被允许，例如用户不允许删除项目
`404 Not Found`	无法访问资源，例如找不到资源 ID，或用户无权访问该资源
`405 Method Not Allowed`	不支持该请求方法
`409 Conflict`	冲突的资源已存在，例如创建已存在名称的项目
`412 Precondition Failed`	请求被拒绝，例如在带有 `If-Unmodified-Since` 头时删除期间被修改的资源
`418 I'm a teapot`	请求被拒绝，请求疑似不安全
`422 Unprocessable`	无法处理实体
`429 Too Many Requests`	用户超过了应用程序速率限制，默认 400/分、4000/小时
`500 Server Error`	处理请求时服务器上出了问题
`503 Service Unavailable`	服务器暂时过载，无法处理请求
`504 Time Out`	响应超时

401：确认令牌是否随请求发出（三种传递方式见鉴权），以及是否已失效。
403：令牌有效但缺少权限，检查令牌的权限范围与该资源的可见性。
404：核对路径参数（如 {owner}、{repo}、ID）与实际资源，私有资源在无权限时也可能返回 404。
422 / 400：按接口页面的参数表核对必填项与取值。
429：按返回的限流信息退避后重试，不要在到达上限后继续并发打请求。
5xx / 504：服务端或网络层面的临时问题，用指数退避重试；对 POST 这类会改变状态的请求，重试前先确认上一次是否已生效，避免重复创建。