错误处理
GeniSpace API 使用标准 HTTP 状态码表示请求结果，并在响应中提供一个扁平的错误体。
HTTP 状态码
| 状态码 | 含义 | 说明 |
|---|---|---|
200 | 成功 | 请求正常处理 |
201 | 已创建 | 资源创建成功 |
400 | 请求错误 | 请求参数无效或缺失 |
401 | 未认证 | 缺少或无效的凭证 |
402 | 需要付费 | Token 余额或配额不足 |
403 | 禁止访问 | 无权限执行该操作 |
404 | 未找到 | 请求的资源不存在 |
429 | 请求过多 | 超出每日 Token 使用上限 |
500 | 服务器错误 | 服务端内部错误 |
错误响应格式
错误体是扁平的——message 和 code 与 success: false 一同位于顶层。不存在嵌套的 error 对象。
{
"success": false,
"message": "Validation failed: name cannot be empty",
"code": "VALIDATION_ERROR"
}
校验失败时还可能额外包含一个带字段级细节的 errors 数组。
常见错误码
| 错误码 | HTTP 状态 | 说明 |
|---|---|---|
VALIDATION_ERROR | 400 | 请求参数无效（express-validator 校验失败） |
BAD_REQUEST | 400 | 请求格式错误 |
UNAUTHORIZED | 401 | 凭证无效或已过期 |
PAYMENT_ERROR | 400 | 支付或计费失败 |
FORBIDDEN | 403 | 无权限访问该资源 |
NOT_FOUND | 404 | 资源不存在 |
SERVER_ERROR | 500 | 服务器内部错误 |
Token 与计费错误
当请求因 Token 余额或配额限制无法处理时，API 会返回以下之一：
| 错误码 | HTTP 状态 | 说明 |
|---|---|---|
INSUFFICIENT_TOKENS | 402 | Token 余额已耗尽 |
BELOW_MINIMUM_BALANCE | 402 | 余额低于该操作所需的最低值 |
REQUEST_TOO_LARGE | 400 | 请求载荷超出单次请求的 Token 上限 |
DAILY_LIMIT_EXCEEDED | 429 | 已达到每日 Token 使用上限 |
错误处理建议
- 检查状态码：根据 HTTP 状态码判断请求是否成功
- 解析错误信息：读取顶层
message，并根据code进行分支判断以获取具体原因 - 重试策略：对
429和5xx错误实施退避重试 - 处理计费错误：将
402响应视为需要为空间充值 Token 余额的信号 - 日志记录：记录错误信息便于排查问题