快速开始
错误处理
API 错误码和错误响应格式
错误响应格式
当请求失败时，API 返回以下格式：
{
"success": false,
"code": "VALIDATION_ERROR",
"message": "验证失败",
"data": null,
"errors": {
"email": "邮箱格式不正确"
},
"timestamp": "2026-01-15T08:30:00Z"
}
HTTP 状态码
| 状态码 | 说明 |
|---|---|
200 | 请求成功 |
201 | 资源创建成功 |
204 | 资源删除成功 |
400 | 请求参数错误 |
401 | 未认证或 Token 过期 |
403 | 无权限访问 |
404 | 资源不存在 |
409 | 资源冲突 |
415 | 不支持的媒体类型 |
429 | 请求频率超限 |
500 | 服务器内部错误 |
503 | 服务不可用 |
401 处理
当收到 401 响应时：
- 尝试使用
refreshToken刷新 Access Token - 使用新的 Token 重试原始请求
- 如果刷新也失败，引导用户重新登录
400 请求参数错误
当提交的字段验证失败时，errors 对象包含每个字段的错误信息：
{
"success": false,
"code": "VALIDATION_ERROR",
"message": "验证失败",
"errors": {
"password": "密码长度至少 8 个字符"
}
}
TypeScript 辅助函数
@momohub/types 包提供了错误处理辅助函数：
import { getApiErrorMessage, getApiErrorCode } from '@momohub/types'
try {
const res = await $fetch('/characters', { method: 'POST', body })
} catch (error) {
const message = getApiErrorMessage(error, '操作失败')
const code = getApiErrorCode(error)
console.error(`[${code}] ${message}`)
}