错误处理

GeniSpace API 使用标准 HTTP 状态码表示请求结果，并在响应体中提供详细的错误信息。

HTTP 状态码

状态码	含义	说明
200	成功	请求正常处理
201	已创建	资源创建成功
400	请求错误	请求参数无效或缺失
401	未认证	缺少或无效的 API 密钥
403	禁止访问	无权限执行该操作
404	未找到	请求的资源不存在
429	请求过多	超出速率限制
500	服务器错误	服务端内部错误

错误响应格式

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "参数 'name' 不能为空",
    "details": {}
  }
}

常见错误码

错误码	HTTP 状态	说明
UNAUTHORIZED	401	API 密钥无效或已过期
FORBIDDEN	403	无权限访问该资源
NOT_FOUND	404	资源不存在
INVALID_PARAMETER	400	请求参数不合法
RATE_LIMIT_EXCEEDED	429	请求频率超出限制
INTERNAL_ERROR	500	服务器内部错误
INSUFFICIENT_TOKENS	402	Token 余额不足

错误处理建议

1. 检查状态码：根据 HTTP 状态码判断请求是否成功
2. 解析错误信息：读取响应体中的 error.message 获取具体原因
3. 重试策略：对 429 和 5xx 错误实施退避重试
4. 日志记录：记录错误信息便于排查问题

相关文档

• API 认证 — 认证方式说明
• API 端点 — 可用端点列表