# API 业务错误码

失败时 HTTP 状态码为 4xx 或 5xx，响应体为 {"code": 错误码, "message": 说明, "data": {"error": {...}}}，data.error 里有 code、retryable（原样重试是否可能成功），以及可选的 path、item_key、next_action、errors。存量查询接口（活码、模板与子码、表单与记录、分区、指标）失败时 code 是数字，与 HTTP 状态码相同，data 为空对象。此外，凡是以 INVALID_ 开头的错误码都表示请求参数不合法（HTTP 400），按 message 和 path 修正入参即可，不逐个列出。http_status 为 null 的错误码不会让整个请求失败，只出现在成功响应的 data.errors、data.warnings、reason 或逐项结果里。

通用的数字 `code`、限流和存量接口的 `error_code` 见[错误码与调用额度](https://cli.im/open-api/openapi/v2/error-codes.md)。本页由 [openapi.json](https://cli.im/open-api/openapi/v2/overview.md#%E6%8E%A5%E5%8F%A3%E8%A7%84%E8%8C%83-openapi-json) 生成。

## 会让请求失败的错误码

| 错误码 | HTTP 状态 | 含义 | 怎么处理 |
|---|---|---|---|
| `unauthorized` | 401 | 凭证无效，或无法确认凭证对应的组织和身份。 | 检查 Authorization 请求头里的凭证是否正确、是否已过期或被撤销。 |
| `permission_denied` | 403 | 凭证的档位不包含这个接口需要的 scope。 | 换用档位足够的个人 API Key，或重新授权并选择更高的档位；所需档位见接口的 x-min-access-level。 |
| `credential_type_not_allowed` | 403 | 组织 Key 不能调用这个接口。 | 改用个人 API Key 或 OAuth access token；组织 Key 可调用的接口见 x-org-key-allowed。 |
| `operation_disabled` | 403 | 当前组织没有开放这类调用。 | 联系草料二维码确认组织的接口开通情况。 |
| `rate_limited` | 429 | 请求过于频繁，或当日读取额度用完后被降低了频率。 | 按响应头 Retry-After 的秒数等待后重试，并降低调用频率。 |
| `quota_exceeded` | 429 | 当日的新建额度已用完，或被进行中的操作暂时占用。 | 用 usage/get 查看额度：被占用时等待进行中的操作结束，用完时等到 reset_at 之后；不要换幂等键重复提交。 |
| `usage_policy_unavailable` | 503 | 额度策略暂时无法读取，写入暂停。 | 稍后用原幂等键重试。 |
| `usage_guard_unavailable` | 503 | 额度服务暂时不可用。 | 稍后重试。 |
| `payload_too_large` | 413 | 请求体超过 1 MiB。 | 拆成多次请求。 |
| `invalid_argument` | 422 | 请求里有不能表示为 JSON 的值。 | 检查数字等字段的内容。 |
| `not_configured` | 503 | 这项能力在当前环境没有配置。 | 联系草料二维码确认。 |
| `upstream_timeout` | 503 | 业务服务处理超时，结果未知。 | 写操作用原幂等键重试，或先查询是否已经生效；不要换键重发。 |
| `upstream_unavailable` | 503 | 业务服务暂时不可用。 | 稍后重试；写操作用原幂等键。 |
| `upstream_protocol_error` | 502 | 业务服务返回了无法识别的结果。 | 写操作先查询是否已经生效，再决定是否用原幂等键重试。 |
| `PERMISSION_DENIED` | 403 | 当前身份没有这个分区或资源的管理权限。 | 确认成员在该分区的权限，或换到有权限的分区。 |
| `SCOPE_DENIED` | 403 | 凭证不包含这项操作需要的权限范围。 | 换用档位足够的凭证，或重新授权。 |
| `MEMBERSHIP_DENIED` | 403 | 凭证对应的账号不是该组织的成员。 | 确认凭证所属的组织。 |
| `ACCOUNT_INACTIVE` | 403 | 账号当前不可用。 | 确认账号状态。 |
| `CAPABILITY_DISABLED` | 404 | 这项能力当前没有开放。 | 用 auth/getContext 查看可用的操作。 |
| `ACCESS_LEVEL_READ_ONLY` | 403 | 组织的最高权限是“只读”，不能新建、修改或删除。 | 由超级管理员在后台“API Key 管理 → 组织策略”放宽最高权限；重试没有用。 |
| `AI_EDIT_CHANNEL_REQUIRED` | 403 | 修改类操作的请求来源没有被识别。 | 通过本文档的接口发起修改；问题持续时联系草料二维码。 |
| `AI_EDIT_ORIGIN_UNAVAILABLE` | 503 | 暂时无法确认这项内容是否由接口创建，没有做修改。 | 稍后重试。 |
| `AI_DELETE_DISABLED` | 403 | 组织的最高权限不到“完全”，不能通过接口删除内容。 | 在草料二维码后台删除；或由超级管理员把组织最高权限设为“完全”。 |
| `TEMPLATE_EDIT_UNSUPPORTED` | 422 | 这个模板的名称和字段不支持通过接口修改。 | 在草料二维码后台修改。只改正文图文组件时，patch 里只放 components（templates/getSchema 的 capabilities.replace_components 为 true 时可用）。 |
| `QRCODE_EDIT_UNSUPPORTED` | 422 | 这个码包含不支持通过接口修改的内容。 | 在草料二维码后台修改。 |
| `DESTRUCTIVE_FIELD_CHANGE_UNSUPPORTED` | 400 | 不能删除已有字段或修改字段类型。 | 只新增字段、修改名称或调整顺序；确需删除请在草料二维码后台操作。 |
| `INVALID_COMPONENT_REF` | 400 | ref 指向的组件不存在，或不能在这里修改。 | 只使用 qrcodes/getEditState 或 templates/getSchema 返回的 components[].ref；绑定了字段的组件按子码取值，用 qrcodeChildren/edit 修改。 |
| `TEMPLATE_RESOURCE_SAVE_FAILED` | 503 | 模板已提交保存，但其中的文件或图片没有确认保存成功。 | 重新读取模板核对实际内容，不要直接重复提交。 |
| `ORG_TEMPLATE_MANAGED` | 403 | 这是组织统一管理的模板，不能通过接口修改或用来生成二维码。 | 由组织模板的管理员在后台调整。 |
| `TEMPLATE_LOCKED` | 403 | 模板已被锁定或停用。 | 在草料二维码后台解锁后重试。 |
| `QRCODE_LOCKED` | 403 | 码已被锁定。 | 在草料二维码后台解锁后重试。 |
| `QRCODE_VERSION_CONFLICT` | 409 | 码在读取之后被改动过。 | 重新调用 qrcodes/getEditState 取最新内容和 version，再基于最新内容修改。 |
| `TEMPLATE_VERSION_CONFLICT` | 409 | 模板在读取之后被改动过。 | 重新调用 templates/getSchema 取最新的 template_version，再重新预校验或预览。 |
| `FORM_VERSION_CONFLICT` | 409 | 表单在读取之后被改动过。 | 重新调用 forms/getEditState 取最新内容和 version。 |
| `BATCH_PLAN_EXPIRED` | 410 | 生成二维码方案已超过 30 分钟有效期。 | 重新调用 qrcodes/prevalidate 生成新方案。 |
| `BATCH_PLAN_NOT_FOUND` | 404 | 找不到这个生成二维码方案，可能已过期或不属于当前凭证。 | 重新预校验。 |
| `GALLERY_PLAN_EXPIRED` | 410 | 官方模板生成二维码方案已超过 30 分钟有效期。 | 重新调用 gallery/prepare-creation。 |
| `GALLERY_TEMPLATE_CHANGED` | 409 | 官方模板在准备方案之后有更新。 | 重新读取模板并重新准备方案。 |
| `PREVIEW_CONFIRMATION_REQUIRED` | 409 | 这次修改会影响已有子码，需要先预览。 | 调用 templates/previewEdit，把返回的 preview_token 和同一份 patch 一起提交。 |
| `DELETE_CONFIRMATION_REQUIRED` | 409 | 缺少有效的删除确认令牌，或令牌与要删除的目标不一致。 | 先调用 previewDelete 接口，10 分钟内用返回的 confirm_token 删除同一批目标。 |
| `IDEMPOTENCY_CONFLICT` | 409 | 同一个幂等键已经用于另一份不同的请求。 | 重试必须使用完全相同的参数；新的请求换一个幂等键。 |
| `IDEMPOTENCY_IN_PROGRESS` | 409 | 同一个请求正在处理中。 | 稍后用原幂等键再次请求取得结果，不要换键重发。 |
| `IDEMPOTENCY_OUTCOME_UNKNOWN` | 409 | 上一次请求的结果未知，可能已经创建了内容。 | 先查询核对；确认没有创建后，再用新的幂等键重做。 |
| `IDEMPOTENCY_EXPIRED` | 409 | 这个幂等键对应的记录已过期。 | 先核对之前是否已创建，再用新的幂等键提交。 |
| `IDEMPOTENCY_UNAVAILABLE` | 503 | 暂时无法登记本次请求，没有执行写入。 | 稍后用原幂等键重试。 |
| `TASK_RECEIPT_EXPIRED` | 410 | 任务回执已过期，不能再查询逐项结果。 | 用 templates/listQrcodes 读取模板下的子码核对。 |
| `CATEGORY_DENIED` | 403 | 指定的目录不存在或不属于这个分区。 | 用 qrcodes/listCreateTargets 查询可用目录；建模板和批量生成二维码通常不需要传目录。 |
| `QRCODE_NOT_FOUND` | 404 | 找不到这个码，可能已删除或不属于当前组织。 | 核对 qrcode_id 是否来自接口返回。 |
| `TEMPLATE_NOT_FOUND` | 404 | 找不到这个模板，可能已删除或不属于当前组织。 | template_id 必须是批量模板的 ID，不能用官方模板 ID 或子码 ID。 |
| `FORM_NOT_FOUND` | 404 | 找不到这个表单，可能已删除或不属于当前组织。 | 核对 form_id。 |
| `TASK_NOT_FOUND` | 404 | 找不到这个任务，可能不属于当前凭证或已过期。 | 核对 task_id，并用提交任务时的同一个凭证查询。 |
| `QRCODE_KIND_MISMATCH` | 422 | 这个接口不适用于该类型的码。 | 先用 qrcodes/getEditState 查看 kind，再调用对应的修改接口；批量模板用 templates/edit。 |
| `FORM_IN_USE` | 409 | 表单还关联着码，不能删除。 | 先在草料二维码后台解除关联。 |
| `CYCLE_PLAN_NOT_FOUND` | 404 | 找不到这个周期计划。 | 核对 plan_id、project_id 和 plan_scope 是否与 cyclePlans/list 的结果一致。 |
| `CYCLE_QUERY_REJECTED` | 422 | 周期查询的参数不被接受。 | 核对计划所在的分区、时间范围和 period_key。 |
| `CYCLE_QUERY_UNAVAILABLE` | 503 | 周期数据暂时无法读取。 | 稍后重试。 |
| `GALLERY_TEMPLATE_NOT_FOUND` | 404 | 官方模板库里读不到这个模板：ID 不对，或模板未发布、未公开。 | 核对 gallery_template_id，或用 gallery/list 搜索。 |
| `GALLERY_SINGLE_INSTALL_UNSUPPORTED` | 422 | 这个官方模板不支持生成单个码。 | 查看 gallery/get 的 compatibility：can_create 为 true 时用 gallery/prepare-creation 批量生成二维码。 |
| `GALLERY_CATEGORY_NOT_FOUND` | 404 | 找不到这个官方模板分类。 | 使用 gallery/categories 返回的 category_id。 |
| `GALLERY_PACKAGE_UNAVAILABLE` | 503 | 这个官方模板的安装包暂时不可用。 | 稍后重试，或换一个模板。 |
| `GALLERY_QUERY_UNAVAILABLE` | 503 | 官方模板库暂时无法查询。 | 稍后重试。 |
| `GALLERY_EXTRA_FIELDS_UNSUPPORTED` | 422 | 这个官方模板不支持追加字段。 | 准备方案时返回：去掉 extra_fields 重新准备。执行方案时返回：模板已安装但没有生成二维码，用 templates/listEditable 找到它，再用 qrcodes/prevalidate 和 qrcodes/createBatch 生成二维码，不要重新安装。 |
| `GALLERY_FIELD_MAPPING_UNAVAILABLE` | 503 | 模板已安装，但暂时无法确定字段的对应关系，子码还没有创建。也可能以 HTTP 409 返回。 | 稍后用原方案和原幂等键重试，不要重新准备方案。 |
| `GALLERY_INSTALL_FAILED` | 503 | 官方模板安装没有成功。 | 先用 templates/listEditable 确认是否已出现新模板，确认没有后再重新准备方案。 |
| `TEMPLATE_UNSUPPORTED` | 422 | 这个模板不支持通过接口批量生成二维码。 | 查看 templates/getSchema 的 capabilities，或换一个模板。 |
| `VALIDATION_FAILED` | 422 | 提交的数据没有通过校验。 | 逐项原因在 data.error.errors 里，按 path 定位修正后重新提交。 |
| `ASSET_UNAVAILABLE` | 422 | 引用的文件还没有上传完成，或已失效。预校验时出现在 data.errors 里。 | 用 assets/getUpload 确认状态为 temporary_available 后再使用。 |
| `ASSET_LIMIT_EXCEEDED` | 422 | 引用的图片或附件数量超过上限。预校验时出现在 data.errors 里。 | 减少文件数量或拆成多批。 |
| `BATCH_CYCLE_OVERRIDE_UNSUPPORTED` | 400 | 批量生成二维码不能单独指定表单或周期，子码沿用模板的设置。 | 去掉请求里的 forms、cycle；需要调整请修改模板。 |
| `URL_BLOCKED` | 422 | 网址命中了平台禁用的域名。 | 更换链接。 |
| `BATCH_SUBMISSION_FAILED` | 503 | 批量任务没有提交成功。 | 用原幂等键重试；不要换键，以免重复生成二维码。 |
| `TASK_RESULTS_UNAVAILABLE` | 409 | 暂时无法取得逐项结果。也可能以 HTTP 503 返回。 | 稍后重试查询，不要重新提交整批。 |
| `TASK_SERVICE_UNAVAILABLE` | 503 | 任务服务暂时不可用。 | 稍后用原任务 ID 重新查询。 |
| `DOMAIN_OPERATION_FAILED` | 503 | 业务服务处理失败，结果可能未知。 | 先查询核对是否已经生效，再决定是否用原幂等键重试。 |
| `LABEL_STYLE_NOT_CONFIGURED` | 409 | 这个码或模板还没有配置标签样式。 | 在草料二维码后台配置标签样式后再导出。 |
| `LABEL_READONLY_UNSUPPORTED` | 503 | 标签服务暂时不能按当前样式生成，没有做任何操作。 | 稍后重试。 |
| `LABEL_TARGET_NOT_READY` | 409 | 码的内容还没有保存就绪，暂时不能生成标签。 | 确认 qrcodeTasks/getResults 里该项为 succeeded 后再试。 |
| `LABEL_TARGETS_MUST_SHARE_TEMPLATE` | 400 | 一次只能处理同一个批量模板下的子码，普通码和子码不能混在一起。 | 按模板分开请求。 |
| `LABEL_FORMAT_UNSUPPORTED` | 400 | 当前标签样式不支持这个导出格式。 | 使用 labels/getConfig 返回的 supported_formats。 |

## 出现在成功响应里的提示码

| 提示码 | 含义 | 怎么处理 |
|---|---|---|
| `AI_EDIT_NOT_AI_CREATED` | 这项内容不是通过接口创建的，读写档的凭证不能修改。作为请求失败返回时为 HTTP 403。 | 在草料二维码后台修改；或由超级管理员把组织最高权限设为“完全”，并改用“完全”档的凭证。 |
| `AI_EDIT_SCOPE_REQUIRED` | 组织的最高权限是“完全”，但当前凭证不是“完全”档，不能修改人工创建的内容。作为请求失败返回时为 HTTP 403。 | 改用“完全”档的个人 API Key，或重新授权并选择“完全”。 |
| `AI_ORIGIN_MARK_FAILED` | 内容已创建，但“接口创建”标记没有写入，之后可能无法通过接口修改它。 | 用原幂等键和原参数重试一次以补写标记；不要新建第二份。 |
| `CHILD_CONTENT_UNCONFIRMED` | 子码已提交保存，但读回的内容与提交的不一致或暂时读不到。 | 用 qrcodes/getEditState 读取这个子码核对；内容正确就不需要再改，不要重复提交。 |
| `QRCODE_CONTENT_UNCONFIRMED` | 码已创建或保存，但读回的内容没有逐项确认。 | 读取这个码核对实际内容；保留返回的 qrcode_id，不要另建一个。 |
| `FORM_CONTENT_UNCONFIRMED` | 表单已保存，但读回的内容没有确认。 | 用 forms/getEditState 核对，不要另建一份。 |
| `FORM_BINDING_UNCONFIRMED` | 码或模板已建好，但表单绑定没有确认成功。 | 读取核对；保留已建好的 ID，不要重新创建。 |
| `CYCLE_SAVE_UNCONFIRMED` | 表单已建好，但周期计划没有确认保存。 | 用 cyclePlans/list 按 form_id 核对；保留已建的表单，不要新建第二份。 |
| `QUIZ_SAVE_UNCONFIRMED` | 表单已建好，但计分设置没有确认保存。 | 核对后再使用，不要新建第二份。 |
| `CONTENT_NOT_READY` | 码已创建，字段或附件还在保存中。 | 稍后再查询 qrcodeTasks/getResults。 |
| `CATEGORY_PLACEMENT_ADJUSTED` | 模板的实际存放目录与请求的目录不同，属正常情况。 | 以返回的 category_id 为准；批量生成二维码时不必再传目录。 |
| `GALLERY_MASTER_TEMPLATE_REQUIRED` | 这是单个码的模板，不能用来批量生成二维码。 | compatibility.can_create_single 为 true 时用 gallery/create-qrcode；要批量生成二维码请换一个批量模板。 |
| `GALLERY_PLACEHOLDER_REQUIRED` | 这个模板没有可以逐码填写的字段，不能用来批量生成二维码。 | compatibility.can_create_single 为 true 时用 gallery/create-qrcode；要批量生成二维码请换一个模板。 |
| `UNKNOWN_FIELD` | 字段 ID 不在模板里，或它不是可以逐码填写的字段。 | 使用 templates/getSchema 返回的 field_id，不要用字段名称。 |
| `REQUIRED_FIELD` | 必填字段没有填值。 | 补上该字段的值。 |
| `INVALID_TYPE` | 字段值的类型或格式不对。 | 文本传字符串，数字传数字，日期传 YYYY-MM-DD，图片和附件传 [{"file_key": ...}]。 |
| `INVALID_ASSET` | 图片或附件的引用无效。也可能以 HTTP 400 返回。 | 先用 assets/requestUpload 上传，确认状态为 temporary_available 后引用返回的 file_key；不接受外部网址。 |
| `ASSET_EXPIRED` | 临时文件已过期。 | 重新上传后再引用。 |
| `ASSET_NOT_FOUND` | 找不到这个文件引用。 | file_key 只能由上传它的同一个凭证使用。 |
| `DUPLICATE_ITEM_KEY` | items 里的 item_key 有重复。 | 每一项使用不同的 item_key。 |
| `BATCH_LIMIT` | 单批数量超过上限，或为空。 | 拆成多批提交，每批最多 100 项。 |
| `BATCH_TASK_FAILED` | 批量任务执行失败，无法确认这一项的结果。 | 查看逐项结果，确认哪些已经建成后再处理剩余部分。 |
