API 请求错误排查

BeanToken 通过 HTTP 状态码 + 结构化错误信息 返回异常原因，可根据下表快速定位问题。

通用 HTTP 状态码

状态码	含义	常见原因
400	请求参数有误	参数缺失/非法、格式错误、内容命中安全拦截
401	鉴权失败	API Key 缺失、错误、已失效
403	权限/账户异常	套餐过期、余额不足、无访问权限
404	资源不存在	模型不存在、资源地址错误
429	请求限流	超出调用频率、额度用尽
500	服务内部异常	平台网关错误，建议稍后重试

详细错误码与处理方案

HTTP 状态	错误类型	错误码	处理建议
400	BadRequest	MissingParameter	缺少必填参数，对照文档补全
400	BadRequest	InvalidParameter	参数值非法，检查参数格式与取值
400	BadRequest	InvalidArgumentError（MissingRole）	messages 数组缺少 role 字段
400	BadRequest	InvalidArgumentError.UnknownRole	role 仅支持 system / user / assistant
400	BadRequest	SensitiveContentDetected	输入内容包含敏感信息，更换内容重试
400	BadRequest	OutputSensitiveContentDetected	生成内容违规，调整输入后重试
400	BadRequest	SensitiveContentDetected.PolicyViolation	内容违反平台规则，请修改后重试
401	Unauthorized	AuthenticationError	检查 API Key 及 Authorization 请求头
403	Forbidden	InvalidSubscription	套餐未订阅/已过期，请续订套餐
403	Forbidden	InvalidAccountStatus	账号状态异常，提交工单处理
403	Forbidden	AccountOverdueError	账户余额不足，请前往充值
403	Forbidden	AccessDenied	无资源访问权限，联系管理员
404	NotFound	ModelNotFound	模型不存在或无权限，核对 model 名称
404	NotFound	UnsupportedModel	当前模型不支持对应服务，更换模型
404	NotFound	ResourceNotFound	资源地址错误，核对接口路径
429	TooManyRequests	RateLimitExceeded.RPM	超出每分钟请求数限制，降低调用频率
429	TooManyRequests	RateLimitExceeded.TPM	超出每分钟 Token 限制，稍后重试
429	TooManyRequests	AccountRateLimitExceeded	账号整体触发限流，暂停高频请求
500	InternalServerError	InternalServiceError	服务内部故障，多次报错请联系客服