API 错误参考

本指南记录了 TeamDay API 的所有错误代码、响应格式和故障排除步骤。

错误响应格式

所有 API 错误都遵循一致的 JSON 结构：

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Detailed error description"
}

字段：

error (boolean) - 错误响应时始终为 true
statusCode (number) - HTTP 状态代码
statusMessage (string) - 人类可读的状态
message (string) - 详细的错误说明

HTTP 状态代码

2xx 成功

这些不是错误，而是成功响应：

200 OK

含义： 请求成功

用于：

GET 请求（列表、获取详情）
PATCH 请求（更新）
DELETE 请求（软删除）
POST 请求（取消执行）

201 Created

含义： 资源成功创建

用于：

POST 请求（创建代理、任务）

4xx 客户端错误

这些错误指示请求有问题。

400 Bad Request

含义： 无效的请求参数或缺少必需字段

常见原因：

缺少必需字段
字段值无效
JSON 格式错误
查询参数无效

401 Unauthorized

含义： 身份验证失败或缺失

常见原因：

缺少 Authorization 标头
无效令牌
令牌过期
令牌格式不正确

403 Forbidden

含义： 已认证但对此操作未授权

常见原因：

用户缺少所需权限
组织访问被撤销
资源属于其他组织

404 Not Found

含义： 资源不存在

常见原因：

资源 ID 无效
资源已删除
资源属于其他组织
端点 URL 中有拼写错误

429 Too Many Requests

含义： 超出速率限制

状态： 当前未强制执行，但将来可能实施

500 Internal Server Error

含义： 意外服务器错误

常见原因：

数据库连接问题
服务依赖失败
未处理的异常
配置错误

503 Service Unavailable

含义： 服务暂时不可用

常见原因：

计划维护
系统过载
依赖服务宕机

错误处理最佳实践

1. 总是检查状态代码

const response = await fetch('https://us.teamday.ai/api/v1/agents', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})

if (!response.ok) {
  const error = await response.json()
  console.error(`API Error ${error.statusCode}: ${error.message}`)
}

2. 处理特定错误情况

async function handleApiError(response) {
  const error = await response.json()

  switch (error.statusCode) {
    case 400:
      // 验证错误
      console.error('Invalid request:', error.message)
      break
    case 401:
      // 认证错误
      console.error('Authentication failed:', error.message)
      break
    case 404:
      // 未找到
      console.error('Resource not found:', error.message)
      break
    case 500:
      // 服务器错误
      console.error('Server error:', error.message)
      break
  }
}

3. 实现重试逻辑

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options)

      if (response.ok) {
        return await response.json()
      }

      const error = await response.json()

      // 不重试客户端错误 (4xx)
      if (error.statusCode >= 400 && error.statusCode < 500) {
        throw new Error(error.message)
      }

      // 使用指数退避重试服务器错误 (5xx)
      if (i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }

      throw new Error(error.message)

    } catch (err) {
      if (i === maxRetries - 1) throw err
    }
  }
}

获取帮助

文档：

需要帮助？

📧 电子邮件：support at teamday.ai
💬 Discord：加入社区
🐛 问题：GitHub

最后更新： 2025 年 12 月 9 日