本文档列出了 API 可能返回的所有错误码及其含义和解决方案。
所有错误响应都遵循统一的格式:
{
"code": 400,
"message": "请求参数错误",
"data": null,
"errors": [
{
"field": "email",
"message": "邮箱格式不正确"
}
],
"timestamp": "2024-01-01T00:00:00Z",
"path": "/api/users"
}
状态码 | 含义 | 说明 |
---|
200 | OK | 请求成功 |
201 | Created | 资源创建成功 |
202 | Accepted | 请求已接受,正在处理 |
204 | No Content | 请求成功,无返回内容 |
状态码 | 含义 | 常见原因 | 解决方案 |
---|
400 | Bad Request | 请求参数错误 | 检查请求参数格式和必需字段 |
401 | Unauthorized | 未授权访问 | 检查 API Token 是否有效 |
403 | Forbidden | 权限不足 | 确认用户权限或联系管理员 |
404 | Not Found | 资源不存在 | 检查请求的资源 ID 或路径 |
405 | Method Not Allowed | 请求方法不允许 | 使用正确的 HTTP 方法 |
409 | Conflict | 资源冲突 | 检查资源是否已存在 |
422 | Unprocessable Entity | 数据验证失败 | 检查数据格式和验证规则 |
429 | Too Many Requests | 请求频率限制 | 降低请求频率或等待 |
状态码 | 含义 | 常见原因 | 解决方案 |
---|
500 | Internal Server Error | 服务器内部错误 | 联系技术支持 |
502 | Bad Gateway | 网关错误 | 稍后重试或联系技术支持 |
503 | Service Unavailable | 服务不可用 | 稍后重试 |
504 | Gateway Timeout | 网关超时 | 稍后重试 |
错误码 | 错误信息 | 说明 | 解决方案 |
---|
1001 | 用户不存在 | 指定的用户 ID 不存在 | 检查用户 ID 是否正确 |
1002 | 邮箱已存在 | 注册时邮箱已被使用 | 使用其他邮箱或找回密码 |
1003 | 密码错误 | 登录密码不正确 | 检查密码或重置密码 |
1004 | 用户已被禁用 | 用户账户被管理员禁用 | 联系管理员解除禁用 |
1005 | 邮箱格式错误 | 邮箱地址格式不正确 | 使用正确的邮箱格式 |
1006 | 密码强度不足 | 密码不符合安全要求 | 使用更强的密码 |
错误码 | 错误信息 | 说明 | 解决方案 |
---|
2001 | Token 无效 | API Token 格式错误或已失效 | 重新获取有效的 Token |
2002 | Token 已过期 | API Token 已超过有效期 | 刷新 Token 或重新登录 |
2003 | 权限不足 | 当前用户权限不足 | 联系管理员提升权限 |
2004 | 登录失败次数过多 | 短时间内登录失败次数过多 | 等待一段时间后重试 |
2005 | 验证码错误 | 输入的验证码不正确 | 重新获取验证码 |
2006 | 验证码已过期 | 验证码已超过有效期 | 重新获取验证码 |
错误码 | 错误信息 | 说明 | 解决方案 |
---|
3001 | 数据不存在 | 请求的数据记录不存在 | 检查数据 ID 是否正确 |
3002 | 数据已存在 | 创建的数据已存在 | 使用更新操作或检查唯一性 |
3003 | 数据格式错误 | 提交的数据格式不正确 | 检查数据格式和类型 |
3004 | 必需字段缺失 | 缺少必需的字段 | 补充所有必需字段 |
3005 | 字段长度超限 | 字段值超过最大长度 | 缩短字段值长度 |
3006 | 数据关联错误 | 关联的数据不存在或无效 | 检查关联数据的有效性 |
错误码 | 错误信息 | 说明 | 解决方案 |
---|
4001 | 系统维护中 | 系统正在维护 | 等待维护完成 |
4002 | 服务暂不可用 | 服务临时不可用 | 稍后重试 |
4003 | 请求超时 | 请求处理超时 | 稍后重试或优化请求 |
4004 | 存储空间不足 | 服务器存储空间不足 | 联系技术支持 |
4005 | 配置错误 | 系统配置错误 | 联系技术支持 |
错误码 | 错误信息 | 说明 | 解决方案 |
---|
5001 | 操作不允许 | 当前状态下不允许此操作 | 检查业务状态 |
5002 | 余额不足 | 账户余额不足 | 充值或检查余额 |
5003 | 库存不足 | 商品库存不足 | 选择其他商品或等待补货 |
5004 | 订单状态错误 | 订单状态不允许此操作 | 检查订单状态 |
5005 | 时间限制 | 操作超出时间限制 | 在允许的时间内操作 |
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;
}
}
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']}")
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
在开发环境中,可以请求更详细的错误信息:
const response = await fetch('/api/users', {
headers: {
'Authorization': 'Bearer ' + token,
'X-Debug': 'true'
}
});
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);
}
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));
}
}
}
如果遇到文档中未列出的错误码或需要技术支持,请:
- 记录完整的错误信息
- 提供请求的详细信息(URL、参数、头部等)
- 通过以下方式联系我们:
- 技术支持邮箱:support@example.com
- 在线客服:https://example.com/support
- GitHub Issues:https://github.com/username/autodoc/issues