错误码 | MaiToken

HTTP 状态码用于表示请求的整体处理结果。
业务错误码位于响应体的 error.code 字段中，用于说明具体错误原因。
错误类型位于 error.type 字段中，便于程序统一识别和处理同类异常。

建议优先根据业务错误码排查，并结合错误信息和处理建议修正请求。若问题仍未解决，请向技术支持提供请求时间、业务错误码和请求 ID（如响应中包含），请勿提供完整 API Key。

错误码	HTTP 状态码	可能原因	处理建议
`key_invalid`	401	未提供 API Key，或 API Key 不正确、不存在	检查请求头中的 API Key 是否完整、有效，并确认没有多余空格或字符
`key_disabled`	401	当前 API Key 已被禁用	前往控制台检查 Key 状态，启用该 Key 或创建新的 API Key
`user_disabled`	403	API Key 所属账号已被禁用	检查账号状态；如需进一步协助，请联系技术支持
`ip_rejected`	403	当前请求 IP 不在 API Key 的 IP 白名单中	将出口 IP 加入白名单，或使用白名单内的网络发起请求
`rate_limited`	429	请求频率超过当前 API Key 或账号的速率限制	降低并发或请求频率，并采用指数退避策略重试；如需更高限额，请联系技术支持
`key_quota_exhausted`	429	当前 API Key 或账号的调用额度已用完	前往控制台检查额度与用量，调整额度后重试
`user_balance_exhausted`	402	账号可用余额不足	充值或调整可用余额后重试
`bad_request`	400	请求路径或请求体中缺少模型名称	按接口文档填写正确的 `model` 参数
`bad_request`	400	请求体为空、格式不正确或传输不完整	检查 JSON 格式、`Content-Type` 请求头及请求体是否完整
`bad_request`	400	请求路径中的模型名称与请求体中的模型名称不一致	将路径和请求体中的模型名称修改为一致
`bad_request`	413	请求体超过接口允许的大小	减少请求内容或文件大小；普通非二进制接口的请求体应小于 32 MiB
`model_not_found`	404	模型名称不正确、当前 API Key 无权使用该模型，或模型暂时不可用	检查模型名称和 Key 权限，并确认模型当前可用；必要时稍后重试或改用其他模型
`task_not_found`	404	异步任务 ID 不存在、任务不属于当前账号，或任务记录已失效	检查任务 ID，并使用创建该任务的账号和 API Key 查询
`unsupported_endpoint`	404	请求的接口路径或操作暂不受支持	对照接口文档检查请求地址和操作名称
`client_cancelled`	499	客户端在服务完成响应前主动断开连接或取消请求	检查客户端超时设置和网络连接，确认需要结果时不要提前取消请求
`internal_error`	500	平台当前请求处理繁忙，为保障计费和数据一致性暂时拒绝请求	稍后重试；建议使用指数退避策略，持续出现时请联系技术支持
`internal_error`	503	平台暂时无法获取 API Key 的鉴权信息	稍后重试；持续出现时请联系技术支持
`internal_error`	503	平台暂时无法校验账号额度或余额	稍后重试，并在控制台确认余额和额度状态
`internal_error`	503	模型服务配置暂时不可用	稍后重试或改用其他可用模型；持续出现时请联系技术支持
`internal_error`	503	平台暂时无法获取异步任务信息	稍后使用原任务 ID 重试查询；请勿立即重复创建任务
`upstream_rate_limited`	429	当前模型服务繁忙，所有可用通道均触发限流	降低请求频率并稍后重试，或临时改用其他模型
`upstream_exhausted`	502	多个模型服务通道尝试后仍未成功完成请求	稍后重试或改用其他模型；持续出现时请联系技术支持
`stream_interrupted_after_first_byte`	200	流式响应已开始返回，但模型服务在传输过程中中断，因此 HTTP 状态码仍为 200	客户端应同时监听流内错误事件；可根据业务需要重新发起请求

错误响应示例

以下示例表示请求使用的 API Key 无效。HTTP 状态码为 401，业务错误码为 key_invalid，错误类型为 authentication_error：

{  "error": {    "code": "key_invalid",    "type": "authentication_error",    "message": "invalid api key"  }}

客户端处理建议

收到 400、401、402、403 或 404 时，请先检查请求参数、身份凭证、余额、权限及资源是否存在，修正后再重试。
收到 429 时，请降低请求频率，并使用指数退避策略重试。
收到 500、502 或 503 时，可在短暂等待后重试；建议设置最大重试次数，避免无限重试。
对流式请求，即使 HTTP 状态码为 200，也应继续监听响应流中的错误信号。
请勿在日志、工单或聊天中提交完整 API Key。