叶动文档中心叶动文档中心
叶动官网
使用指南
接口文档
  • 简体中文
  • English
GitHub
叶动官网
使用指南
接口文档
  • 简体中文
  • English
GitHub
  • � 接口文档

    • 接口文档
    • API 认证指南
    • API 使用示例
    • 错误码参考

错误码参考

本文档列出了 API 可能返回的所有错误码及其含义和解决方案。

📋 错误响应格式

所有错误响应都遵循统一的格式:

{
  "code": 400,
  "message": "请求参数错误",
  "data": null,
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    }
  ],
  "timestamp": "2024-01-01T00:00:00Z",
  "path": "/api/users"
}

🔢 HTTP 状态码

2xx 成功状态码

状态码含义说明
200OK请求成功
201Created资源创建成功
202Accepted请求已接受,正在处理
204No Content请求成功,无返回内容

4xx 客户端错误

状态码含义常见原因解决方案
400Bad Request请求参数错误检查请求参数格式和必需字段
401Unauthorized未授权访问检查 API Token 是否有效
403Forbidden权限不足确认用户权限或联系管理员
404Not Found资源不存在检查请求的资源 ID 或路径
405Method Not Allowed请求方法不允许使用正确的 HTTP 方法
409Conflict资源冲突检查资源是否已存在
422Unprocessable Entity数据验证失败检查数据格式和验证规则
429Too Many Requests请求频率限制降低请求频率或等待

5xx 服务器错误

状态码含义常见原因解决方案
500Internal Server Error服务器内部错误联系技术支持
502Bad Gateway网关错误稍后重试或联系技术支持
503Service Unavailable服务不可用稍后重试
504Gateway Timeout网关超时稍后重试

🔍 业务错误码

用户相关错误 (1000-1999)

错误码错误信息说明解决方案
1001用户不存在指定的用户 ID 不存在检查用户 ID 是否正确
1002邮箱已存在注册时邮箱已被使用使用其他邮箱或找回密码
1003密码错误登录密码不正确检查密码或重置密码
1004用户已被禁用用户账户被管理员禁用联系管理员解除禁用
1005邮箱格式错误邮箱地址格式不正确使用正确的邮箱格式
1006密码强度不足密码不符合安全要求使用更强的密码

认证相关错误 (2000-2999)

错误码错误信息说明解决方案
2001Token 无效API Token 格式错误或已失效重新获取有效的 Token
2002Token 已过期API Token 已超过有效期刷新 Token 或重新登录
2003权限不足当前用户权限不足联系管理员提升权限
2004登录失败次数过多短时间内登录失败次数过多等待一段时间后重试
2005验证码错误输入的验证码不正确重新获取验证码
2006验证码已过期验证码已超过有效期重新获取验证码

数据相关错误 (3000-3999)

错误码错误信息说明解决方案
3001数据不存在请求的数据记录不存在检查数据 ID 是否正确
3002数据已存在创建的数据已存在使用更新操作或检查唯一性
3003数据格式错误提交的数据格式不正确检查数据格式和类型
3004必需字段缺失缺少必需的字段补充所有必需字段
3005字段长度超限字段值超过最大长度缩短字段值长度
3006数据关联错误关联的数据不存在或无效检查关联数据的有效性

系统相关错误 (4000-4999)

错误码错误信息说明解决方案
4001系统维护中系统正在维护等待维护完成
4002服务暂不可用服务临时不可用稍后重试
4003请求超时请求处理超时稍后重试或优化请求
4004存储空间不足服务器存储空间不足联系技术支持
4005配置错误系统配置错误联系技术支持

业务逻辑错误 (5000-5999)

错误码错误信息说明解决方案
5001操作不允许当前状态下不允许此操作检查业务状态
5002余额不足账户余额不足充值或检查余额
5003库存不足商品库存不足选择其他商品或等待补货
5004订单状态错误订单状态不允许此操作检查订单状态
5005时间限制操作超出时间限制在允许的时间内操作

🛠 错误处理示例

JavaScript 错误处理

async function handleAPIError(response) {
  if (!response.ok) {
    const errorData = await response.json();
    
    switch (response.status) {
      case 400:
        console.error('请求参数错误:', errorData.message);
        // 显示具体的字段错误
        if (errorData.errors) {
          errorData.errors.forEach(error => {
            console.error(`字段 ${error.field}: ${error.message}`);
          });
        }
        break;
        
      case 401:
        console.error('认证失败:', errorData.message);
        // 跳转到登录页面
        window.location.href = '/login';
        break;
        
      case 403:
        console.error('权限不足:', errorData.message);
        // 显示权限不足提示
        alert('您没有权限执行此操作');
        break;
        
      case 404:
        console.error('资源不存在:', errorData.message);
        break;
        
      case 429:
        console.error('请求过于频繁:', errorData.message);
        // 实现退避重试
        setTimeout(() => {
          // 重试请求
        }, 5000);
        break;
        
      case 500:
        console.error('服务器错误:', errorData.message);
        // 显示友好的错误提示
        alert('服务器暂时出现问题,请稍后重试');
        break;
        
      default:
        console.error('未知错误:', errorData.message);
    }
    
    throw new APIError(response.status, errorData.message, errorData);
  }
  
  return response.json();
}

// 自定义错误类
class APIError extends Error {
  constructor(status, message, data) {
    super(message);
    this.name = 'APIError';
    this.status = status;
    this.data = data;
  }
}

Python 错误处理

import requests
from requests.exceptions import RequestException

class APIError(Exception):
    def __init__(self, status_code, message, data=None):
        self.status_code = status_code
        self.message = message
        self.data = data
        super().__init__(self.message)

def handle_api_response(response):
    """处理 API 响应和错误"""
    try:
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError:
        error_data = response.json()
        
        if response.status_code == 400:
            print(f"请求参数错误: {error_data['message']}")
        elif response.status_code == 401:
            print(f"认证失败: {error_data['message']}")
            # 重新获取 token
        elif response.status_code == 403:
            print(f"权限不足: {error_data['message']}")
        elif response.status_code == 404:
            print(f"资源不存在: {error_data['message']}")
        elif response.status_code == 429:
            print(f"请求过于频繁: {error_data['message']}")
            # 实现重试逻辑
        elif response.status_code >= 500:
            print(f"服务器错误: {error_data['message']}")
        
        raise APIError(
            response.status_code, 
            error_data['message'], 
            error_data
        )
    except RequestException as e:
        print(f"网络请求失败: {e}")
        raise

🔧 调试技巧

1. 启用详细错误信息

在开发环境中,可以请求更详细的错误信息:

const response = await fetch('/api/users', {
  headers: {
    'Authorization': 'Bearer ' + token,
    'X-Debug': 'true'  // 启用调试模式
  }
});

2. 错误日志记录

function logError(error, context) {
  const errorLog = {
    timestamp: new Date().toISOString(),
    error: {
      status: error.status,
      message: error.message,
      data: error.data
    },
    context: context,
    userAgent: navigator.userAgent,
    url: window.location.href
  };
  
  // 发送到日志服务
  console.error('API Error:', errorLog);
  
  // 可选:发送到错误监控服务
  // sendToErrorMonitoring(errorLog);
}

3. 重试机制

async function retryRequest(requestFn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await requestFn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // 对于某些错误码不进行重试
      if ([400, 401, 403, 404].includes(error.status)) {
        throw error;
      }
      
      // 指数退避
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

📞 获取帮助

如果遇到文档中未列出的错误码或需要技术支持,请:

  1. 记录完整的错误信息
  2. 提供请求的详细信息(URL、参数、头部等)
  3. 通过以下方式联系我们:
    • 技术支持邮箱:support@example.com
    • 在线客服:https://example.com/support
    • GitHub Issues:https://github.com/username/autodoc/issues

🔗 相关资源

  • API 概述
  • 认证指南
  • 使用示例
在 GitHub 上编辑此页
Prev
API 使用示例