API 错误

API 通过标准 HTTP 状态码和统一的响应体报告错误。成功响应直接返回数据,不带包装信封。

错误格式

发生错误时,响应体是带有 error 字段的 JSON 对象,包含人类可读的消息:

{"error":"reaction not found"}

请优先根据 HTTP 状态码进行判断,error 文本用于日志记录和向用户提示。

状态码

  • 200 OK — 请求成功,响应体包含数据。
  • 201 Created — 新资源已创建(部分 POST 端点)。
  • 204 No Content — 成功但无响应体(部分删除操作)。
  • 400 Bad Request — 请求体或参数不正确。
  • 401 Unauthorized — 令牌缺失、无效或已过期;或该路由不支持个人令牌访问。
  • 402 Payment Required — 操作受套餐或配额限制(例如,自定义媒体存储需要 premium)。
  • 403 Forbidden — 令牌缺少此路由所需的访问范围。
  • 404 Not Found — 资源不存在或不属于你。
  • 409 Conflict — 状态冲突(例如,唯一值重复)。
  • 422 Unprocessable Entity — 请求体语法正确,但未通过业务规则验证。
  • 429 Too Many Requests — 超过请求频率限制(参见限制)。
  • 500 Internal Server Error — 服务器内部错误;请稍后重试。

处理方式

2xx 代码视为成功。遇到 401/403 时,检查令牌及其访问范围。遇到 4xx(除 429 外)时,请勿原样重试——先修正请求。遇到 4295xx 时,可使用指数退避进行重试。

下一步