错误与状态码

解读 API 问题响应,恢复失败的请求,并区分 HTTP 请求失败与翻译任务失败。

解码成功响应前,请先检查 HTTP 状态。https://api.lingo.dev/v2 处的 API 通过 JSON 问题详情报告失败。成功获取作业并不意味着其中的任务已成功完成,因此还需检查作业状态。

解读问题响应 #

问题响应使用 Content-Type: application/problem+json。常见字段包括 type、title、status 和 detail;具名问题还包含标识受影响资源或修复方式的字段。

以下示例表示本地化作业不存在:

json
{
  "type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
  "title": "Localization job not found",
  "status": 404,
  "detail": "Localization job lfr_example not found.",
  "id": "lfr_example"
}

type URI 用于标识问题。请查阅 API 错误目录,了解各具名问题的字段和端点。存储错误或为错误分类时,请保持返回的 URI 不变。

修正无效请求 #

未通过验证的请求会返回 400 请求错误,并包含 type: "about:blank"。如果有验证详情,errors 会列出每个问题的 path 和 message:

json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "path": ["payload", "documents", 0, "source"],
      "message": "Expected a JSON object"
    }
  ]
}

路径以待验证的请求部分开头,例如 payload,后接属性名和从零开始的数组索引。此示例指向请求体中第一个 documents 条目内的 source。重新提交前,请对照端点的结构定义修正指定的值。about:blank 是通用问题类型,因此在具名错误目录中没有对应条目。

选择恢复方式 #

HTTP 状态常见原因下一步操作
400请求不符合路由的结构定义。根据返回的验证详情,修正路径、查询参数、标头或请求体。
401凭据缺失、无效或已过期。加载所需的密钥,或续期用户会话。
402额度不足、套餐功能不可用,或服务密钥在 RBAC 降级后被禁用。查看具体的问题条件,并满足相应的账户或套餐要求。
403缺少权限或必需的用户身份,或受到功能开关限制。检查调用方及该操作的访问要求。
404资源不存在,或对当前调用方不可见。检查标识符、组织和资源权限。
409操作与资源的当前状态冲突。读取当前资源。根据提示上传缺失的产物、完成正在运行的任务,或刷新已关闭的审核。
413上传内容或请求体超出大小限制。缩减输入内容或拆分任务;每个产物的上传大小上限为 25 MiB。
422请求结构有效,但违反了操作约束。修正指定的问题,例如无效的审核编辑或重复使用的幂等键。
429已达到用量或操作限制。如果问题响应提供了重试时间,请按该时间重试;否则,请先检查账户限制再重试。
5xx服务器或依赖服务无法完成请求。保留资源 ID 和请求 ID;是否重试及如何重试,应遵循该操作的语义。

detail 说明具体的失败原因;仅凭状态码无法完整地对错误分类。来自代理或网络故障的响应可能不包含问题响应体。请保留其 HTTP 状态和可读的响应文本,以便诊断,但不要在日志中记录敏感信息。

重试本地化提交 #

发送创建请求前,请保存其 Idempotency-Key。如果响应丢失,请使用该键重新发送相同的创建请求,以获取原始作业。使用新键会创建新任务。

创建后,请保存作业 ID。在决定是否创建另一个作业前,先读取该作业。上传内容的字节必须与其 SHA-256 地址所标识的字节完全一致;启动前,请补齐所有缺失的上传。重复调用 /start 仍会作用于同一个作业。

准入检查在启动时进行。出现 DailyTokenLimitReached 或额度不足时,作业会保持待处理状态,账户问题解决后仍可启动。反复创建新作业并不能解决账户限制问题。

区分请求失败与任务失败 #

GET /v2/localization/jobs/:id 返回 HTTP 200 表示已获取作业,但其 status._tag 仍可能是 Failed。请查看 status.message、每个目标的状态,以及阶段警告与失败信息。

即使某个目标失败,已完成的目标仍可下载。请保留这些结果,排除失败原因后,仅提交需要重新生成的任务。客户端轮询超时不会取消作业。

预配有专门的各类型的结果与恢复方式。审核决策有专门的审核已关闭和编辑无效错误。恢复时,请依据这些资源的状态处理,不要一遇到失败就重复原始写入操作。