错误与限流

错误响应结构、完整的 HTTP 状态码表、限流行为，以及适用于 Atlas Cloud 的重试策略。

错误响应结构

Atlas Cloud 会根据你调用的 API 部分返回三种不同的错误结构。写解析逻辑之前请先确认是哪一种。

用于 LLM 协议端点和媒体生成端点：

{
  "code": 401,
  "msg": "unauthorized",
  "request_id": "…",
  "data": null
}

每个响应都带有 X-Request-ID 响应头。请记录下来——这是支持团队追踪某次具体调用最快的方式。

HTTP 状态码

状态码	含义	该怎么做
`400`	请求格式错误：请求体无法解析、缺少 `model`、Content-Type 不对、留存策略请求头无效，或 `webhook_url` 不合法	修正请求。`msg` 字段会指出具体问题
`401`	身份验证失败——密钥缺失、无效或已过期	检查密钥。注意：URL 路径写错同样会返回 401，所以也请核对端点
`402`	余额不足，或 Coding Plan 额度已用尽	充值
`403`	账户或用户无权限——包括用 Coding Plan 密钥调用不接受该类密钥的模型	检查密钥权限范围，或联系技术支持
`404`	资源不存在。对模型而言，这也包括你的账户无权使用的模型	对照模型库核对模型 ID
`413`	请求体超过 50 MB	改用 URL 而不是内联 Base64，或先上传文件
`429`	触发限流	退避后重试——见下文
`451`	你所在地区被限制访问	不可重试
`500`	内部错误	重试一次，仍失败则带上 request ID 反馈
`503`	服务暂时不可用	退避后重试
`504`	同步请求超过最大等待时间	改用异步流程并轮询

401 并不总是意味着密钥有问题。网关先鉴权后路由，因此路径写错也会产生 401 而不是 404。如果同一个密钥在别处能用，请先检查 URL。

任务级错误码

异步任务失败时，data.error_code 会带一个平台数字错误码，比 HTTP 状态码更具体。例如 1039 表示输入被内容审核拒绝。

data.error 里是可读的错误描述。请把两者连同 prediction ID 一起记录下来。

限流

限流按账户和模型分别生效。超出限制会返回 429。

LLM 和媒体端点不会返回 X-RateLimit-Limit、X-RateLimit-Remaining 或 Retry-After。你无法从响应头读取剩余配额——请在客户端自行实现退避。

/public/v1 计费端点是个例外：它们的 429 响应确实带有 Retry-After。

如果生产环境需要更高的限额，请联系我们，并说明预期的请求量和使用的模型组合。

重试策略

对 429、500、503、504 以及网络层错误进行重试。不要重试 400、401、402、403、404 或 451——重试结果完全一样。

读取类请求可以放心重试。但重试生成任务的提交请求要谨慎：一个超时的请求可能其实已经被受理，盲目重试会创建（并计费）第二个任务。更稳妥的做法是异步提交加轮询，这样即使丢了响应，也不会丢掉任务。

import time, random, requests

RETRYABLE = {429, 500, 503, 504}

def call_with_retry(url, payload, api_key, max_attempts=4):
    for attempt in range(max_attempts):
        response = requests.post(
            url,
            json=payload,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=60,
        )
        if response.status_code not in RETRYABLE:
            return response

        if attempt == max_attempts - 1:
            break

        # 指数退避 + 抖动，避免大量客户端同时重试
        delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
        time.sleep(delay)

    return response

流式响应中的错误

如果流式请求在流建立之前就失败，你会收到一个普通的 HTTP 错误。一旦流已经开始，连接会保持打开，错误会以事件的形式出现在流中——所以流式调用返回 200 并不保证响应是完整的。请务必处理流中途中断的情况。

流中还可能包含以 : 开头的 SSE 注释行，用作 keep-alive 信号。它们不是数据，必须忽略——大多数 SSE 客户端会帮你处理，但自己手写的解析器往往不会。

获取帮助

反馈问题时，请提供：

失败响应中的 X-Request-ID 响应头
异步任务的 prediction ID
准确的模型 ID 和时间戳

请通过技术支持联系我们。

错误响应结构

HTTP 状态码

任务级错误码

限流

重试策略

流式响应中的错误

获取帮助

相关内容

LLM API 协议

预测任务

API Key

On this page