MossHubAPI 文档
开发者文档 错误码

错误码

下载代码

网关错误沿用你调用的协议格式;按状态码和错误类型排查,联系维护人员时带上请求编号。

格式

网关自己返回的错误跟着你调用的接口走,与背后是哪条上游线路无关。响应类型为 application/json,说明文字是英文,文案可能调整,程序判断请用状态码和类型字段。错误体里没有请求编号,请看响应头 X-Request-Id。

接口错误格式判断字段
/v1/chat/completions、/v1/responses、/v1/embeddings、/v1/images/generations、/v1/images/edits、/v1/modelsOpenAIerror.type、error.code
/v1/messages、/v1/messages/count_tokensAnthropicerror.type
/v1beta/models/...Geminierror.status
/minimax/v2/...MiniMax 视频error.type
/minimax/v1/t2a_v2MiniMax 语音base_resp.status_code
/ark/api/v3/...火山方舟error.code

/v1/models 请求带 anthropic-version 头时返回 Anthropic 格式。

OpenAI 格式:

{
  "error": {
    "code": "invalid_api_key",
    "message": "invalid API key",
    "param": null,
    "type": "invalid_request_error"
  }
}

Anthropic 格式:

{
  "error": {
    "message": "invalid API key",
    "type": "authentication_error"
  },
  "type": "error"
}

其他格式:Gemini 返回 error.code(HTTP 状态码)、error.message 和 error.status;MiniMax 视频返回顶层 type(值为 error)以及 error.type、error.message 和字符串形式的 error.http_code;MiniMax 语音返回 base_resp.status_code 和 base_resp.status_msg;火山方舟返回 error.code、error.message、error.param 和 error.type,其中 error.type 是去掉空格的 HTTP 状态名,例如 TooManyRequests。

网关返回的状态码

状态原因OpenAI type · codeAnthropic typeGemini status
400请求体读不出来或缺少模型,用了网关不支持的功能,或模型不在这个接口提供invalid_request_error · nullinvalid_request_errorINVALID_ARGUMENT
401缺少密钥、密钥无效或已过期invalid_request_error · invalid_api_keyauthentication_errorUNAUTHENTICATED
402密钥所属的预算已用完insufficient_quota · insufficient_quotabilling_errorRESOURCE_EXHAUSTED
403密钥的模型范围不含这个模型invalid_request_error · model_not_allowedpermission_errorPERMISSION_DENIED
404模型不存在invalid_request_error · model_not_foundnot_found_errorNOT_FOUND
413请求体超过 32 MiBinvalid_request_error · request_too_largerequest_too_largeINVALID_ARGUMENT
429模型的所有上游线路都没有余量,带 Retry-Afterrequests · rate_limit_exceededrate_limit_errorRESOURCE_EXHAUSTED
502连不上上游,上游响应无法读取或转换,或上游拒绝了网关的账号server_error · upstream_failedapi_errorUNAVAILABLE
503网关还没加载模型目录,或模型、视频任务的上游暂时不可用server_error · service_unavailableapi_errorUNAVAILABLE
504上游没有按时响应server_error · upstream_timeouttimeout_errorDEADLINE_EXCEEDED

MiniMax 与火山方舟接口的状态码含义相同,类型字段如下。视频任务不存在或无权访问时也返回 404,取消已经开始生成的任务返回 400。

状态MiniMax 视频 error.typeMiniMax 语音 base_resp.status_code火山方舟 error.code
400bad_request_error2013InvalidParameter
401authorized_error1004AuthenticationError
402insufficient_balance_error1008AccountOverdueError
403permission_error1004AccessDenied
404not_found_error2013模型为 InvalidEndpointOrModel.NotFound,任务为 ResourceNotFound
413bad_request_error2013RequestTooLarge
429rate_limit_error1002ServerOverloaded
502server_error1033InternalServiceError
503server_error1000ServiceUnavailable
504server_error1001RequestTimeout

路径或请求方法不对时返回的 404 不是 JSON,请检查基础地址和路径。

上游返回的错误

表外的状态码和错误码来自上游:

  • 上游返回 400、422 这类请求本身的错误时,网关不换线路,原样返回状态码和响应体。
  • 上游返回 401、402、403、404、408、429 或 5xx 时,网关先换线路重试,都失败时返回最后一次的错误。其中 401、402、403 说明上游不接受网关的账号,与你的密钥无关,网关改为返回 502。
  • 网关转换了协议时(响应头带 X-Mosshub-Translated),上游错误会改写成你调用的协议格式。
  • 上游响应头只透传 Content-Type、Retry-After、Retry-After-Ms、X-Should-Retry 和 Anthropic-Ratelimit-Unified-*。
  • MiniMax 语音的上游业务错误可能以 200 返回,错误在 base_resp.status_code。

流式响应中途出错

流式响应开始后,状态码已经是 200。之后出错时,网关这样结束响应:

接口结束方式
/v1/chat/completions直接结束,没有 data: [DONE]
/v1/responsesresponse.failed 事件
/v1/messageserror 事件
/minimax/v1/t2a_v2一条 base_resp.status_code 为 1033 的事件

报障编号

编号位置用途
X-Request-Id每个响应的响应头服务端为每个请求生成,客户端不能指定;调用记录的请求编号就是它,联系维护人员时提供它和请求时间
X-Client-Request-Id你发送的请求头,可选你自己的关联编号,最长 128 个可打印 ASCII 字符,不合规时忽略;随调用记录保存,不用于去重
上游请求 ID「我的用量」的调用详情上游给这次调用的编号,用于和上游对账

怎么处理

状态处理
400、404、413修改请求,原样重发结果相同
401、403检查密钥和它的模型范围
402申请追加额度,见额度申请与飞书审批
429按 Retry-After 等待后重试,见限流与超时
502、503、504退避后重试
实际可调用的模型、授权与价格以控制台为准。
页面字体:MiSans(小米,依《MiSans 字体知识产权许可协议》使用);Google Sans Flex(SIL Open Font License 1.1)。

本页目录