错误与重试

业务错误在响应体顶层返回 code 和 message。detail 多数时候与 message 相同，但也可能是另一段较短的说明（如下例），展示给用户时以 message 为准：

{
  "code": "CONCURRENCY_LIMITED",
  "message": "排队中的文件已达上限（1000 个），请等部分文件翻译完成后再提交",
  "detail": "排队文件完成一部分后可继续提交"
}

少数业务错误只返回 code。参数校验失败返回 422，detail 为字段错误列表：

{
  "detail": [
    { "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" }
  ]
}

请先按 HTTP 状态处理错误，再看 code：许多错误只返回通用的 UNKNOWN_ERROR，只有部分错误带有具体的 code（如下文 429 的几种）。请记录响应头中的 X-Request-Id 以便排查。

HTTP 状态

状态	含义	建议
400	请求无效，例如所选配置当前不可用	修正请求，不要重试
401	凭据缺失、无效、过期或已撤销	更换凭据
402	余额（已扣除欠款）未高于任务门槛，或余额为负；使用 API Key 时也可能是该 Key 的剩余额度不足	充值（或调高 Key 额度）后重新提交
403	Key 的限制或资源归属不允许本次操作	检查 Key 设置与资源归属
404	资源不存在、已删除或不属于当前账号	核对 ID
409	幂等键已用于不同请求，或资源当前状态不允许该操作	查询原操作后再决定
410	资源或接口已永久失效，例如已下线的接口、幂等键对应的任务已删除	不要重试
413	文件或请求体超出上限	减小文件
415	文件格式不支持	更换格式
422	参数校验失败，或文件为空、没有可处理的内容	按字段修正，不要自动重试
429	频率、排队数量或预算受限	见下文
5xx	暂时性服务错误	指数退避，设置最大次数

429 的处理

code	含义	处理
RATE_LIMITED	请求过于频繁	按 Retry-After 等待后重试
CONCURRENCY_LIMITED	排队中的文件翻译任务已达上限	按 Retry-After 等待，或等部分任务完成
AUTH_API_KEY_QUOTA_EXCEEDED	该 Key 的预算已用尽	调高预算前不要重试

没有 Retry-After 的 429 请按指数退避处理。

重试策略

• 查询类请求可以直接重试。
• 创建类请求重试时，沿用同一个 Idempotency-Key 和完全相同的请求体；每次新的提交使用新的键。
• 上传失败时重新申请上传地址。
• 为每次请求设置连接、读取和总超时，重试加入随机抖动，并限制最大次数。

import random
import time

for attempt in range(5):
    response = call_api()
    if response.status_code not in {429, 500, 502, 503, 504}:
        break
    if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED":
        break
    retry_after = response.headers.get("Retry-After")
    delay = float(retry_after) if retry_after else min(2 ** attempt, 16)
    time.sleep(delay + random.random())