开发者文档开始使用
错误
统一的错误结构、稳定的错误码、明确的重试规则。
所有非 2xx 响应都使用同一结构。请根据 error.code 进行分支处理，切勿依据 message。
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| 字段 | 内容 |
|---|---|
code | 稳定不变，snake_case 格式 |
message | 英文，用于日志 |
request_id | 同时出现在 X-Request-Id 中。联系技术支持时请提供 |
details[] | 400/422 时返回：每个问题对应的 path、code、message |
错误码
| 状态码 | 错误码 | 含义 | 处理方式 | 可重试 |
|---|---|---|---|---|
| 400 | invalid_json | 请求体不是有效的 JSON，或某个字段类型错误。 | 修正请求体。 | 否 |
| 401 | unauthorized | API 密钥缺失、格式错误或无法识别。 | 发送 Authorization: Bearer cd_live_…，并检查密钥是否完整复制。 | 否 |
| 401 | key_revoked | 密钥已被撤销。 | 在开发者控制台中创建新密钥。 | 否 |
| 401 | key_expired | 密钥已过期。 | 在开发者控制台中创建新密钥。 | 否 |
| 402 | insufficient_credits | 可用积分不足以支付该任务的最低可能费用。 | 购买积分包或等待月度积分发放；本次未扣费。 | 否 |
| 403 | ip_not_allowed | 调用方 IP 不在该密钥的 IP 白名单中。 | 从允许的 IP 发起调用，或编辑 IP 白名单。 | 否 |
| 403 | subscription_inactive | 组织没有包含 API 的有效订阅。 | 续订您的订阅。 | 否 |
| 403 | account_inactive | 组织已被暂停使用，或其所有者的账户均未处于有效状态。 | 联系技术支持。 | 否 |
| 403 | scope_missing | 密钥缺少此接口所需的权限范围。 | 使用具有所需权限范围的密钥（pack:write、jobs:read、account:read、resources:read、resources:write）。 | 否 |
| 403 | preset_read_only | 预设车辆不能修改或删除。 | 请改为创建自己的车辆：POST /v1/vehicles. | 否 |
| 403 | plan_limit_reached | 组织的套餐已达到项目或货物数量上限。 | 删除不再需要的项目，或升级到更高的套餐。 | 否 |
| 404 | not_found | 没有与此方法和路径匹配的 /v1 接口。 | 对照接口列表检查请求方法和路径。 | 否 |
| 404 | job_not_found | 您的组织中没有此 ID 的任务。 | 检查 ID。 | 否 |
| 404 | vehicle_not_found | 预设车辆和您组织的车辆中都没有此 ID。 | 核对 ID，车辆列表见 GET /v1/vehicles. | 否 |
| 404 | template_not_found | 您的组织中没有此 ID 的模板。 | 核对 ID，模板列表见 GET /v1/templates. | 否 |
| 404 | project_not_found | 您的组织中没有此 ID 的项目。 | 核对 ID，项目列表见 GET /v1/projects. | 否 |
| 409 | job_not_finished | 任务仍在排队或运行中。 | 轮询 GET /v1/jobs/{id}，直到 status 为 succeeded。 | 是 |
| 409 | project_busy | 该项目正在进行装载计算（在应用中或由另一个任务执行）。 | 等待该次计算结束后重试。 | 是 |
| 409 | job_failed | 任务失败，没有结果。 | 查看 job.error；因我方原因导致的失败不收费（time_limit_exceeded 按已取消任务计费）。如果是临时原因，请重新提交。 | 否 |
| 409 | job_canceled | 任务已取消，没有结果。 | 如有需要，请重新提交。 | 否 |
| 409 | job_already_finished | 任务已结束，无法取消。 | 无需处理。 | 否 |
| 400 | idempotency_key_invalid | Idempotency-Key 请求头超过 128 个字符。 | 使用更短的键（UUID 即可）。 | 否 |
| 410 | result_expired | 结果已超过保留期并被删除。 | 如需再次获取方案，请重新提交任务。 | 否 |
| 413 | payload_too_large | 请求体超过 10 MB。 | 减少物品数量或简化物品。 | 否 |
| 422 | validation_failed | 请求是格式正确的 JSON，但描述的任务无效。details[] 列出了所有问题。 | 逐一修正 details[].path 指出的问题；校验失败不收费。 | 否 |
| 429 | rate_limited | 当前分钟、小时或天内的请求过多（按密钥或按组织计），或您的 IP 地址每分钟认证失败超过 60 次。 | 等待 Retry-After 指定的秒数，然后使用退避策略重试。 | 是 |
| 429 | too_many_jobs | 组织的排队中 + 运行中任务数已达上限。 | 等待运行中的任务完成后重试。 | 是 |
| 500 | internal_error | 服务端发生内部错误。 | 使用退避策略重试；如问题持续，请提供 request_id。 | 是 |
| 503 | api_disabled | API 暂时停用（维护中），或已对该组织关闭。 | 稍后重试。 | 是 |
校验详情
422 validation_failed 中的 details[].code：
| 错误码 | 含义 |
|---|---|
required | 缺少必填字段 |
invalid_value | 类型错误，或不是允许的值之一 |
out_of_range | 过小、过大或过长 |
duplicate_id | 某个 ID 被重复使用 |
unknown_vehicle | 没有与该 vehicle_id 对应的预设车辆或您自己的车辆 |
unknown_template | 您没有与该 template_id 对应的模板 |
type_not_allowed | 该车辆类型未对您的组织开放 |
unknown_group | 物品引用了未列出的分组 |
does_not_fit | 该物品无法装入任何列出的车辆 |
too_many_items | 物品件数超过任务上限 |
too_many_vehicles | 车辆数超过任务上限 |
unknown_field | API 无法识别的字段 |
任务错误
状态为 failed 或 canceled 的任务会在 job.error.code 中说明原因：
| 错误码 | 含义 |
|---|---|
canceled | 任务已被取消，收取任务基础费和已用计算费用。取消接口为 DELETE /v1/jobs/{id}. |
time_limit_exceeded | 在任何车辆装载完成之前，计算时间预算已用完。按已取消任务计费：收取任务基础费、大批量装载附加费和已用计算费用，不收取车辆费用。 |
engine_failed | 装载引擎出错。不收费。 |
queue_timeout | 任务等待计算槽位的时间过长。不收费。 |
server_restarted | 任务排队或运行期间服务重启。不收费。 |
重试
对 429、500 和 503 使用指数退避重试，并遵循 Retry-After。重试时发送相同的 Idempotency-Key（幂等性）。其他 4xx 错误不要原样重试。