错误处理

了解如何正确处理 API 返回的错误信息。

HTTP 状态码

明道云 API 使用标准的 HTTP 状态码：

• 200 OK - 请求成功
• 201 Created - 资源创建成功
• 400 Bad Request - 请求参数错误
• 401 Unauthorized - 认证失败
• 403 Forbidden - 权限不足
• 404 Not Found - 资源不存在
• 429 Too Many Requests - 请求频率过高
• 500 Internal Server Error - 服务器错误

错误响应格式

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "参数验证失败",
    "details": {
      "field": "worksheetId",
      "reason": "不能为空"
    }
  }
}

常见错误码

错误码	说明	解决方案
INVALID_TOKEN	Token 无效	检查 Token 是否正确
TOKEN_EXPIRED	Token 已过期	重新生成 Token
PERMISSION_DENIED	权限不足	检查 Token 权限
RESOURCE_NOT_FOUND	资源不存在	检查资源 ID 是否正确
RATE_LIMIT_EXCEEDED	请求频率过高	降低请求频率

错误处理最佳实践

1. 始终检查状态码

   if (response.status !== 200) {
     throw new Error(`API 错误: ${response.status}`)
   }

2. 处理网络错误

   try {
     const response = await api.get('/records')
   } catch (error) {
     if (error.response) {
       // API 返回了错误响应
       console.error('API 错误:', error.response.data)
     } else {
       // 网络错误
       console.error('网络错误:', error.message)
     }
   }

3. 实现重试机制

   async function retryRequest(fn, maxRetries = 3) {
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn()
       } catch (error) {
         if (i === maxRetries - 1) throw error
         await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)))
       }
     }
   }

4. 记录错误日志

   • 记录完整的错误信息
   • 包含请求参数和响应数据
   • 便于问题排查