Skip to content

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 见错误码与调用额度。本页由 openapi.json 生成。

会让请求失败的错误码 ​

错误码HTTP 状态含义怎么处理
unauthorized401凭证无效,或无法确认凭证对应的组织和身份。检查 Authorization 请求头里的凭证是否正确、是否已过期或被撤销。
permission_denied403凭证的档位不包含这个接口需要的 scope。换用档位足够的个人 API Key,或重新授权并选择更高的档位;所需档位见接口的 x-min-access-level。
credential_type_not_allowed403组织 Key 不能调用这个接口。改用个人 API Key 或 OAuth access token;组织 Key 可调用的接口见 x-org-key-allowed。
operation_disabled403当前组织没有开放这类调用。联系草料二维码确认组织的接口开通情况。
rate_limited429请求过于频繁,或当日读取额度用完后被降低了频率。按响应头 Retry-After 的秒数等待后重试,并降低调用频率。
quota_exceeded429当日的新建额度已用完,或被进行中的操作暂时占用。用 usage/get 查看额度:被占用时等待进行中的操作结束,用完时等到 reset_at 之后;不要换幂等键重复提交。
usage_policy_unavailable503额度策略暂时无法读取,写入暂停。稍后用原幂等键重试。
usage_guard_unavailable503额度服务暂时不可用。稍后重试。
payload_too_large413请求体超过 1 MiB。拆成多次请求。
invalid_argument422请求里有不能表示为 JSON 的值。检查数字等字段的内容。
not_configured503这项能力在当前环境没有配置。联系草料二维码确认。
upstream_timeout503业务服务处理超时,结果未知。写操作用原幂等键重试,或先查询是否已经生效;不要换键重发。
upstream_unavailable503业务服务暂时不可用。稍后重试;写操作用原幂等键。
upstream_protocol_error502业务服务返回了无法识别的结果。写操作先查询是否已经生效,再决定是否用原幂等键重试。
PERMISSION_DENIED403当前身份没有这个分区或资源的管理权限。确认成员在该分区的权限,或换到有权限的分区。
SCOPE_DENIED403凭证不包含这项操作需要的权限范围。换用档位足够的凭证,或重新授权。
MEMBERSHIP_DENIED403凭证对应的账号不是该组织的成员。确认凭证所属的组织。
ACCOUNT_INACTIVE403账号当前不可用。确认账号状态。
CAPABILITY_DISABLED404这项能力当前没有开放。用 auth/getContext 查看可用的操作。
ACCESS_LEVEL_READ_ONLY403组织的最高权限是“只读”,不能新建、修改或删除。由超级管理员在后台“API Key 管理 → 组织策略”放宽最高权限;重试没有用。
AI_EDIT_CHANNEL_REQUIRED403修改类操作的请求来源没有被识别。通过本文档的接口发起修改;问题持续时联系草料二维码。
AI_EDIT_ORIGIN_UNAVAILABLE503暂时无法确认这项内容是否由接口创建,没有做修改。稍后重试。
AI_DELETE_DISABLED403组织的最高权限不到“完全”,不能通过接口删除内容。在草料二维码后台删除;或由超级管理员把组织最高权限设为“完全”。
TEMPLATE_EDIT_UNSUPPORTED422这个模板的名称和字段不支持通过接口修改。在草料二维码后台修改。只改正文图文组件时,patch 里只放 components(templates/getSchema 的 capabilities.replace_components 为 true 时可用)。
QRCODE_EDIT_UNSUPPORTED422这个码包含不支持通过接口修改的内容。在草料二维码后台修改。
DESTRUCTIVE_FIELD_CHANGE_UNSUPPORTED400不能删除已有字段或修改字段类型。只新增字段、修改名称或调整顺序;确需删除请在草料二维码后台操作。
INVALID_COMPONENT_REF400ref 指向的组件不存在,或不能在这里修改。只使用 qrcodes/getEditState 或 templates/getSchema 返回的 components[].ref;绑定了字段的组件按子码取值,用 qrcodeChildren/edit 修改。
TEMPLATE_RESOURCE_SAVE_FAILED503模板已提交保存,但其中的文件或图片没有确认保存成功。重新读取模板核对实际内容,不要直接重复提交。
ORG_TEMPLATE_MANAGED403这是组织统一管理的模板,不能通过接口修改或用来生成二维码。由组织模板的管理员在后台调整。
TEMPLATE_LOCKED403模板已被锁定或停用。在草料二维码后台解锁后重试。
QRCODE_LOCKED403码已被锁定。在草料二维码后台解锁后重试。
QRCODE_VERSION_CONFLICT409码在读取之后被改动过。重新调用 qrcodes/getEditState 取最新内容和 version,再基于最新内容修改。
TEMPLATE_VERSION_CONFLICT409模板在读取之后被改动过。重新调用 templates/getSchema 取最新的 template_version,再重新预校验或预览。
FORM_VERSION_CONFLICT409表单在读取之后被改动过。重新调用 forms/getEditState 取最新内容和 version。
BATCH_PLAN_EXPIRED410生成二维码方案已超过 30 分钟有效期。重新调用 qrcodes/prevalidate 生成新方案。
BATCH_PLAN_NOT_FOUND404找不到这个生成二维码方案,可能已过期或不属于当前凭证。重新预校验。
GALLERY_PLAN_EXPIRED410官方模板生成二维码方案已超过 30 分钟有效期。重新调用 gallery/prepare-creation。
GALLERY_TEMPLATE_CHANGED409官方模板在准备方案之后有更新。重新读取模板并重新准备方案。
PREVIEW_CONFIRMATION_REQUIRED409这次修改会影响已有子码,需要先预览。调用 templates/previewEdit,把返回的 preview_token 和同一份 patch 一起提交。
DELETE_CONFIRMATION_REQUIRED409缺少有效的删除确认令牌,或令牌与要删除的目标不一致。先调用 previewDelete 接口,10 分钟内用返回的 confirm_token 删除同一批目标。
IDEMPOTENCY_CONFLICT409同一个幂等键已经用于另一份不同的请求。重试必须使用完全相同的参数;新的请求换一个幂等键。
IDEMPOTENCY_IN_PROGRESS409同一个请求正在处理中。稍后用原幂等键再次请求取得结果,不要换键重发。
IDEMPOTENCY_OUTCOME_UNKNOWN409上一次请求的结果未知,可能已经创建了内容。先查询核对;确认没有创建后,再用新的幂等键重做。
IDEMPOTENCY_EXPIRED409这个幂等键对应的记录已过期。先核对之前是否已创建,再用新的幂等键提交。
IDEMPOTENCY_UNAVAILABLE503暂时无法登记本次请求,没有执行写入。稍后用原幂等键重试。
TASK_RECEIPT_EXPIRED410任务回执已过期,不能再查询逐项结果。用 templates/listQrcodes 读取模板下的子码核对。
CATEGORY_DENIED403指定的目录不存在或不属于这个分区。用 qrcodes/listCreateTargets 查询可用目录;建模板和批量生成二维码通常不需要传目录。
QRCODE_NOT_FOUND404找不到这个码,可能已删除或不属于当前组织。核对 qrcode_id 是否来自接口返回。
TEMPLATE_NOT_FOUND404找不到这个模板,可能已删除或不属于当前组织。template_id 必须是批量模板的 ID,不能用官方模板 ID 或子码 ID。
FORM_NOT_FOUND404找不到这个表单,可能已删除或不属于当前组织。核对 form_id。
TASK_NOT_FOUND404找不到这个任务,可能不属于当前凭证或已过期。核对 task_id,并用提交任务时的同一个凭证查询。
QRCODE_KIND_MISMATCH422这个接口不适用于该类型的码。先用 qrcodes/getEditState 查看 kind,再调用对应的修改接口;批量模板用 templates/edit。
FORM_IN_USE409表单还关联着码,不能删除。先在草料二维码后台解除关联。
CYCLE_PLAN_NOT_FOUND404找不到这个周期计划。核对 plan_id、project_id 和 plan_scope 是否与 cyclePlans/list 的结果一致。
CYCLE_QUERY_REJECTED422周期查询的参数不被接受。核对计划所在的分区、时间范围和 period_key。
CYCLE_QUERY_UNAVAILABLE503周期数据暂时无法读取。稍后重试。
GALLERY_TEMPLATE_NOT_FOUND404官方模板库里读不到这个模板:ID 不对,或模板未发布、未公开。核对 gallery_template_id,或用 gallery/list 搜索。
GALLERY_SINGLE_INSTALL_UNSUPPORTED422这个官方模板不支持生成单个码。查看 gallery/get 的 compatibility:can_create 为 true 时用 gallery/prepare-creation 批量生成二维码。
GALLERY_CATEGORY_NOT_FOUND404找不到这个官方模板分类。使用 gallery/categories 返回的 category_id。
GALLERY_PACKAGE_UNAVAILABLE503这个官方模板的安装包暂时不可用。稍后重试,或换一个模板。
GALLERY_QUERY_UNAVAILABLE503官方模板库暂时无法查询。稍后重试。
GALLERY_EXTRA_FIELDS_UNSUPPORTED422这个官方模板不支持追加字段。准备方案时返回:去掉 extra_fields 重新准备。执行方案时返回:模板已安装但没有生成二维码,用 templates/listEditable 找到它,再用 qrcodes/prevalidate 和 qrcodes/createBatch 生成二维码,不要重新安装。
GALLERY_FIELD_MAPPING_UNAVAILABLE503模板已安装,但暂时无法确定字段的对应关系,子码还没有创建。也可能以 HTTP 409 返回。稍后用原方案和原幂等键重试,不要重新准备方案。
GALLERY_INSTALL_FAILED503官方模板安装没有成功。先用 templates/listEditable 确认是否已出现新模板,确认没有后再重新准备方案。
TEMPLATE_UNSUPPORTED422这个模板不支持通过接口批量生成二维码。查看 templates/getSchema 的 capabilities,或换一个模板。
VALIDATION_FAILED422提交的数据没有通过校验。逐项原因在 data.error.errors 里,按 path 定位修正后重新提交。
ASSET_UNAVAILABLE422引用的文件还没有上传完成,或已失效。预校验时出现在 data.errors 里。用 assets/getUpload 确认状态为 temporary_available 后再使用。
ASSET_LIMIT_EXCEEDED422引用的图片或附件数量超过上限。预校验时出现在 data.errors 里。减少文件数量或拆成多批。
BATCH_CYCLE_OVERRIDE_UNSUPPORTED400批量生成二维码不能单独指定表单或周期,子码沿用模板的设置。去掉请求里的 forms、cycle;需要调整请修改模板。
URL_BLOCKED422网址命中了平台禁用的域名。更换链接。
BATCH_SUBMISSION_FAILED503批量任务没有提交成功。用原幂等键重试;不要换键,以免重复生成二维码。
TASK_RESULTS_UNAVAILABLE409暂时无法取得逐项结果。也可能以 HTTP 503 返回。稍后重试查询,不要重新提交整批。
TASK_SERVICE_UNAVAILABLE503任务服务暂时不可用。稍后用原任务 ID 重新查询。
DOMAIN_OPERATION_FAILED503业务服务处理失败,结果可能未知。先查询核对是否已经生效,再决定是否用原幂等键重试。
LABEL_STYLE_NOT_CONFIGURED409这个码或模板还没有配置标签样式。在草料二维码后台配置标签样式后再导出。
LABEL_READONLY_UNSUPPORTED503标签服务暂时不能按当前样式生成,没有做任何操作。稍后重试。
LABEL_TARGET_NOT_READY409码的内容还没有保存就绪,暂时不能生成标签。确认 qrcodeTasks/getResults 里该项为 succeeded 后再试。
LABEL_TARGETS_MUST_SHARE_TEMPLATE400一次只能处理同一个批量模板下的子码,普通码和子码不能混在一起。按模板分开请求。
LABEL_FORMAT_UNSUPPORTED400当前标签样式不支持这个导出格式。使用 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_KEYitems 里的 item_key 有重复。每一项使用不同的 item_key。
BATCH_LIMIT单批数量超过上限,或为空。拆成多批提交,每批最多 100 项。
BATCH_TASK_FAILED批量任务执行失败,无法确认这一项的结果。查看逐项结果,确认哪些已经建成后再处理剩余部分。