Documentation

开发者文档

模型 API、图片与视频生成、音频、联网搜索，以及各客户端接入方式。

错误码

先看三样东西：HTTP 状态码、响应里的 error.type 或 error.code、以及 request_id。HTTP 状态告诉你大类，业务码告诉你具体原因，request_id 用来对账和找支持。

响应长什么样

不同入口的包装略有差别，但错误信息都在 error 里。

入口典型响应
文本、图片、视频、音频接口{"error":{"type":"...","message":"...","request_id":"..."}}
Messages 协议入口{"type":"error","error":{"type":"...","message":"..."}}
限流中间件{"success":false,"code":"RATE_LIMITED","message":"...","retry_after":30}
会话鉴权{"success":false,"code":"LOGIN_REQUIRED","message":"..."}

程序里请按 type 或 code 分支，不要按 message 的措辞分支。message 可能调整，request_id 和业务码更适合做稳定判断。

错误码表

按 HTTP 状态码排序。

HTTP 状态业务码含义你该怎么办
400invalid_request_error / INVALID_REQUEST请求体不合法，字段缺失、类型不对或 JSON 解析失败对照接口文档检查字段；不要原样重试
400OUTPUT_BUDGET_CONFLICTmax_tokens 和 max_completion_tokens 同时传了不同的值只传一个；两个都传时必须相同
400CONTEXT_LENGTH_EXCEEDED输入超过模型安全上下文容量缩短输入、减少工具结果或换上下文更大的模型
400MODEL_PROTOCOL_MISMATCH当前入口的协议与模型要求不一致换用模型支持的入口。文本有两个入口，不要一直重试同一种写法
400MEDIA_MODEL_MODE_UNSUPPORTED视频模型不支持你选的长视频/图生视频模式换模型，或去掉 image_url 改用文生视频
400MEDIA_MODEL_PARAMS_INVALID / MEDIA_VIDEO_TASK_INVALID图片/视频参数不合法，或任务 ID 格式不对按模型列表支持的参数重填；任务 ID 用创建时返回的那个
401API_KEY_INVALID密钥无效、已撤销或已过期重新创建密钥；确认 Authorization: Bearer sk-loko-... 没有截断
401LOGIN_REQUIRED / TOKEN_INVALID没有带登录态，或登录态已失效重新登录，或改用长期 API 密钥
402INSUFFICIENT_CREDITS可用积分不足充值或减少本次请求的规模；402 不会调用上游，也不会扣钱
403MODEL_ACCESS_DENIED当前账号或团队无权使用这个模型换模型，或让管理员开通权限；不要靠重试解决
403CHAT_ACCESS_DENIED当前账号没有开通 AI 对话能力开通对话能力后再调用
403TEAM_ACCESS_DENIED / TEAM_PROJECT_ACCESS_DENIED企业空间或企业项目上下文无权限检查 x-lokospace-team-id、x-lokospace-project-id 和成员关系
404MEDIA_MODEL_NOT_FOUND / AUDIO_MODEL_NOT_FOUND模型不存在、已停用，或用错了模型类型到对应的模型列表确认 id；图片、视频、音频不要混用入口
404MEDIA_VIDEO_TASK_NOT_FOUND视频任务不存在，或不属于当前账号用创建时返回的任务 ID，并且用同一账号查询
409REQUEST_ALREADY_SETTLED同一个请求已经结算完成不要重复调用；需要结果就查原请求或换新的业务请求
409REQUEST_IN_PROGRESS相同幂等键的请求正在执行等原请求结束；不要用新幂等键并发重发
409REQUEST_SETTLEMENT_PENDING上游已经返回，账单正在核对不要重放；保留 request_id，等账单核对完成
409MEDIA_RESULT_NOT_CACHED图片已完成并扣费，但 base64 结果没有缓存同一幂等键拿不到旧结果；要重新生成就换新幂等键，这会是新费用
413AUDIO_TOO_LARGE音频文件超过 25MB压缩、切分或改用 audio_url
429RATE_LIMITED入口请求频率或并发超过限制按 Retry-After 或 retry_after 退避后重试
429IP_BLOCKED当前来源 IP 被限制不要继续重试；联系管理员处理
502UPSTREAM_REQUEST_FAILED上游返回错误、超时或响应格式不可用；上游 4xx 时也可能透传 4xx先看 upstream_status；5xx 可退避重试，4xx 先改请求
502UPSTREAM_CREDENTIAL_INVALID / UPSTREAM_CREDENTIAL_QUOTA_EXHAUSTED平台侧渠道凭证失效或额度耗尽这不是你的密钥问题；带 request_id 联系支持，不要反复重试
502CHANNEL_POOL_BUSY模型并发已满，排队超过 queue_timeout_seconds降低客户端并发或稍后重试；不要瞬间放大并发
502CHANNEL_POOL_EXHAUSTED当前渠道没有未尝试的可用凭证稍后重试；持续出现就带 request_id 联系支持
503MODEL_PRICING_MISSING / MODEL_PRICING_INVALID模型没有按 Token 定价，或定价配置无效换模型；这是平台配置问题，不是改请求参数能解决的
503CHANNEL_CREDENTIAL_MISSING模型渠道没有可用凭证稍后重试或联系支持
503MEDIA_MODEL_UNAVAILABLE / MEDIA_PRICING_MISSING图片/视频模型没有活跃定价、渠道停用或模型映射不可用到 /images/models 或 /videos/models 确认模型是否可售
504OFFICIAL_LLM_APPLICATION_TIMEOUT请求超过应用截止时间可以退避重试；如果已经收到部分流式内容，不要盲目重发
504OFFICIAL_LLM_UPSTREAM_STALL / OFFICIAL_LLM_STREAM_STALL上游首字节超时，或流式响应中途长时间没有数据未收到内容时可重试；已收到内容时保留 request_id 对账

几个典型响应

密钥无效：

{
  "error": {
    "type": "invalid_request_error",
    "code": "API_KEY_INVALID",
    "message": "密钥无效、已撤销或已过期"
  }
}

积分不足：

{
  "error": {
    "type": "INSUFFICIENT_CREDITS",
    "message": "积分余额不足",
    "available_credits": 5,
    "request_id": "..."
  }
}

模型无权限：

{
  "error": {
    "type": "MODEL_ACCESS_DENIED",
    "message": "当前账号或团队无权使用官方模型 xxx",
    "request_id": "..."
  }
}

限流：

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "success": false,
  "code": "RATE_LIMITED",
  "message": "请求过于频繁，请稍后再试",
  "retry_after": 30
}

排查顺序

  1. 看 HTTP 状态。4xx 先改请求、密钥、余额或权限；429 和 5xx 才考虑退避重试。
  2. 看业务码。MODEL_ACCESS_DENIED 和 MODEL_PRICING_MISSING 是两种完全不同的问题，不要都当成“模型不存在”。
  3. 看 request_id。把它和 lokospace_billing.requestId 对上，确认是不是同一次调用。
  4. 看 upstream_status。它表示平台到上游那一段的状态，不是你这次请求的最终状态。
  5. 仍然无法判断时，把 request_id、时间、模型名、HTTP 状态和业务码一起给支持。不要发完整密钥。

哪些不要重试

情况原因
400、401、402、403、404、413请求、密钥、余额、权限或资源本身有问题，重试不会变好
409 REQUEST_IN_PROGRESS原请求还在跑，重发只会增加并发
409 REQUEST_SETTLEMENT_PENDING账单待核对，重放可能干扰结算
409 REQUEST_ALREADY_SETTLED已经结算，重复调用不会产生新结果
已收到部分流式内容后的中断可能已经产生真实用量，重发可能产生第二笔费用

429 和 502、503、504 可以重试，但要用退避，不要固定间隔猛打。具体策略见「限流」页。