错误

统一的错误格式、状态码以及各自的处理方法。

所有错误格式统一

每个错误响应都包含相同的字段：statusCode 中是 HTTP 状态，code 中是供程序判断的稳定代码，message 中是供人阅读的说明。说明文字可能会变，代码不会变。

JSON

{
  "statusCode": 404,
  "code": "not_found",
  "message": "work not found"
}

状态码

读取公开 API 时会遇到以下状态码：

400invalid_request参数缺失、类型错误或超出范围。
403forbidden资源存在，但所有者将其设为非公开。
404not_found此地址下没有任何内容。
429rate_limited来自你的地址的请求过多；请稍候再试。
500internal_error我们这边出了问题；请稍后再试。
503unavailable操作所需的某项服务（例如搜索）暂时不可用。

无效参数

当参数缺失或超出范围时，响应为 400 invalid_request，issues 会列出每个问题及对应的参数名。

JSON

{
  "statusCode": 400,
  "code": "invalid_request",
  "message": "The request parameters are not valid.",
  "issues": ["limit: Too big: expected number to be <=50"]
}

已迁移的作品

当两个作品库条目被确认为同一部作品时，其中一个会合并到另一个。请求旧条目会返回 301，并在 movedTo 中给出新的 ID，或新的媒介和 slug。请请求新地址，并更新你保存的内容。

HTTP

HTTP/1.1 301 Moved Permanently

{ "movedTo": "01a0cb02-0a14-7877-911d-5b4dde76df72" }

个人主页的非公开栏目

成员自行决定个人主页的哪些部分公开。被隐藏的栏目会返回 403，并附带指明该栏目的代码，例如 favorites_private、library_private、activity_private 或 communities_private。更改过用户名的成员会返回 404 member_renamed，新名称在 username 中。

JSON

{
  "statusCode": 403,
  "code": "favorites_private",
  "message": "You are not allowed to do this."
}