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 外)时,请勿原样重试——先修正请求。遇到 429 和 5xx 时,可使用指数退避进行重试。