API 错误响应

错误处理

本文档描述了 API 可能返回的错误响应及其处理方式。所有 API 都遵循相同的错误响应格式。

错误响应格式

错误响应 (4xx/5xx)

{
    "success": false,
    "data": null,
    "error": {
        "code": 400,
        "message": "错误信息"
    }
}

通用错误码

以下是所有 API 可能返回的通用错误码：

错误码	说明	错误信息
400	请求参数错误	具体的参数错误信息
401	未认证	"认证失败"
403	无权限访问	"无权限执行此操作"
404	资源不存在	"xxx不存在"
429	请求过于频繁	"请求过于频繁，请稍后再试"
500	服务器内部错误	"服务器内部错误"

项目相关错误码

错误码	说明	错误信息
404	项目不存在	"项目不存在"
404	目标组织不存在	"目标组织不存在"
400	项目已属于目标组织	"项目已属于目标组织"

设备相关错误码

错误码	说明	错误信息
404	设备不存在	"设备不存在"
400	设备已绑定	"设备已绑定到其他项目"

错误处理最佳实践

在客户端处理 API 错误时，建议遵循以下最佳实践：

1. 始终检查响应中的 success 字段
2. 如果 success 为 false，从 error 对象中获取错误信息
3. 根据 error.code 进行不同的错误处理
4. 向用户显示友好的错误信息，可以使用 error.message

示例代码

async function callApi(endpoint, options) {
  try {
    const response = await fetch(endpoint, options);
    const result = await response.json();
    
    if (!result.success) {
      // 处理错误
      console.error(`错误 ${result.error.code}: ${result.error.message}`);
      // 根据错误码进行不同处理
      switch (result.error.code) {
        case 401:
          // 重定向到登录页面
          break;
        case 403:
          // 显示权限不足提示
          break;
        default:
          // 显示一般错误
          break;
      }
      return null;
    }
    
    return result.data;
  } catch (error) {
    console.error('API 请求失败:', error);
    return null;
  }
}