错误码
概述
本文档详细说明了 ZGI API 中的错误码定义、含义和处理建议。所有的 API 响应都遵循统一的错误处理格式，便于开发者进行错误处理和问题排查。
响应格式
成功响应
{
"status_code": 200,
"status_message": "SUCCESS",
"data": {
}
}
错误响应
{
"status_code": 400,
"status_message": "BAD_REQUEST",
"error": {
"code": "INVALID_PARAMETER",
"message": "参数无效",
"details": {
"field": "email",
"reason": "格式不正确"
}
}
}
HTTP 状态码
2xx - 成功
| 状态码 |
说明 |
使用场景 |
| 200 |
请求成功 |
常规成功响应 |
| 201 |
创建成功 |
资源创建成功 |
| 202 |
已接受 |
异步任务已接受 |
| 204 |
无内容 |
删除成功 |
4xx - 客户端错误
| 状态码 |
说明 |
使用场景 |
| 400 |
请求参数错误 |
参数格式、类型错误 |
| 401 |
未授权 |
缺少认证信息或认证失败 |
| 403 |
权限不足 |
无权访问资源 |
| 404 |
资源不存在 |
请求的资源未找到 |
| 409 |
资源冲突 |
资源已存在或状态冲突 |
| 429 |
请求过于频繁 |
超出速率限制 |
5xx - 服务端错误
| 状态码 |
说明 |
使用场景 |
| 500 |
服务器内部错误 |
服务器异常 |
| 502 |
网关错误 |
上游服务异常 |
| 503 |
服务不可用 |
服务维护或过载 |
| 504 |
网关超时 |
上游服务超时 |
业务错误码
通用错误 (10xxx)
| 错误码 |
说明 |
处理建议 |
| 10000 |
系统内部错误 |
联系技术支持 |
| 10001 |
参数无效 |
检查请求参数 |
| 10002 |
资源不存在 |
确认资源标识符 |
| 10003 |
操作不允许 |
检查操作权限 |
| 10004 |
请求过于频繁 |
控制请求频率 |
认证错误 (11xxx)
| 错误码 |
说明 |
处理建议 |
| 11001 |
认证失败 |
检查认证信息 |
| 11002 |
令牌过期 |
刷新访问令牌 |
| 11003 |
令牌无效 |
重新登录获取令牌 |
| 11004 |
权限不足 |
申请所需权限 |
| 11005 |
账号被锁定 |
联系管理员解锁 |
组织错误 (12xxx)
| 错误码 |
说明 |
处理建议 |
| 12001 |
组织不存在 |
检查组织 ID |
| 12002 |
组织已存在 |
使用其他名称 |
| 12003 |
成员已存在 |
检查成员信息 |
| 12004 |
成员不存在 |
确认成员身份 |
| 12005 |
角色无效 |
检查角色设置 |
项目错误 (13xxx)
| 错误码 |
说明 |
处理建议 |
| 13001 |
项目不存在 |
检查项目 ID |
| 13002 |
项目已存在 |
使用其他名称 |
| 13003 |
项目已归档 |
检查项目状态 |
| 13004 |
资源超限 |
升级资源配额 |
| 13005 |
配置无效 |
检查项目配置 |
API 密钥错误 (14xxx)
| 错误码 |
说明 |
处理建议 |
| 14001 |
密钥不存在 |
检查密钥 ID |
| 14002 |
密钥已过期 |
创建新密钥 |
| 14003 |
密钥已禁用 |
启用或更新密钥 |
| 14004 |
超出密钥限制 |
删除未使用密钥 |
| 14005 |
权限设置无效 |
检查权限配置 |
账单错误 (15xxx)
| 错误码 |
说明 |
处理建议 |
| 15001 |
余额不足 |
充值账户 |
| 15002 |
支付失败 |
检查支付信息 |
| 15003 |
订单无效 |
重新创建订单 |
| 15004 |
账单周期无效 |
检查日期范围 |
| 15005 |
价格方案无效 |
确认价格方案 |
错误处理最佳实践
1. 错误检查
try {
const response = await client.organizations.create({
name: 'My Organization'
});
} catch (error) {
if (error.status === 400) {
console.error('参数错误:', error.error.details);
} else if (error.status === 409) {
console.error('组织名称已存在');
} else {
console.error('创建组织失败:', error.message);
}
}
2. 错误重试
async function retryRequest(fn, maxRetries = 3) {
let retries = 0;
while (retries < maxRetries) {
try {
return await fn();
} catch (error) {
if (error.status === 429) {
const delay = Math.pow(2, retries) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
retries++;
} else {
throw error;
}
}
}
throw new Error('超出最大重试次数');
}
3. 错误日志
function logError(error) {
const errorLog = {
timestamp: new Date().toISOString(),
status: error.status,
code: error.error?.code,
message: error.message,
details: error.error?.details
};
console.error('API错误:', errorLog);
}
常见问题
1. 如何处理 429 错误？
- 实现请求重试机制
- 使用指数退避策略
- 监控请求频率
- 优化请求策略
2. 如何处理认证错误？
- 检查认证信息
- 实现令牌刷新
- 处理会话过期
- 提供重新登录选项
3. 如何优化错误提示？
- 提供清晰错误信息
- 给出具体解决建议
- 支持多语言错误提示
- 记录详细错误日志
更新日志
v1.1.0 (2024-02-01)
v1.0.0 (2024-01-01)
- 基础错误码定义
- HTTP 状态码说明
- 错误响应格式规范
