跳到主要内容

错误

错误

每一次失败都带有稳定的错误码。请依据错误码分支，切勿依据提示文字：措辞随时可能改动，错误码不会。

路径、方法、作用域、字段名、错误码和校验规则名称一律以英文发布，因为接口本身的语言就是英文——这些正是调用方需要照原样输入或比对的内容。每一段代码示例、每一个 JSON 载荷，以及错误响应中携带的那句原文，同样如此：/v1 不读取 Accept-Language，把 API 实际发送的内容翻译出来反而会造成误述。围绕它们的说明文字则跟随本页面的语言。

错误信封

所有非 2xx 响应的结构完全一致。documentation_url 直接指向下方对应的条目，request_id 则是提交支持工单时应当附上的值。details 承载机器可读的上下文：请求体被拒绝时即为 issues，其中每一项都以 JSON Pointer 指向出问题的字段。

响应
{
  "error": {
    "code": "validation_failed",
    "message": "The request body failed validation.",
    "documentation_url": "https://passportcraft.com/docs/api/errors#validation_failed",
    "request_id": "req_9Fv2KpQ0aXbT4Lmn",
    "details": {
      "issues": [
        { "source": { "pointer": "/data/product_name" }, "rule": "required" }
      ]
    }
  }
}

错误码

每个错误码都从携带它的响应中直接链接过来，因此打开本页时通常已经定位到所需的条目。

invalid_key

401

所提供的 API 密钥无效。

API 返回The API key provided is not valid.

任何端点都可能返回它。

key_revoked

401

该 API 密钥已被吊销。

API 返回This API key has been revoked.

任何端点都可能返回它。

key_expired

401

该 API 密钥已过期。

API 返回This API key has expired.

任何端点都可能返回它。

key_rotated

401

该 API 密钥已在一次轮换中被替换，其重叠期也已结束。

API 返回This API key was replaced by a rotation and its overlap window has closed.

任何端点都可能返回它。

mode_mismatch

400

密钥前缀与凭据不匹配。请确认您要用的是测试密钥还是正式密钥。

API 返回The key prefix does not match the credential. Check whether you meant a test or a live key.

任何端点都可能返回它。

insufficient_scope

403

该凭据不具备此操作所需的作用域。

API 返回This credential does not carry the scope required for this operation.

哪些端点会返回它

organization_not_found_or_not_granted

404

不存在该组织，或该密钥没有该组织的授权。有人吊销授权，或该组织与其合作伙伴的安排结束时，授权即告终止；此后该组织不再出现在 GET /organizations 中。

API 返回No such organization.

哪些端点会返回它

resource_not_found

404

不存在该资源。

API 返回No such resource.

哪些端点会返回它

wildcard_not_supported

400

组织通配符 “-” 属于保留用法，目前尚不支持。

API 返回The "-" organization wildcard is reserved and not yet supported.

哪些端点会返回它

invalid_request

400

无法解析该请求。

API 返回The request could not be understood.

任何端点都可能返回它。

method_not_allowed

405

端点存在，但不回应这个 HTTP 方法。拒绝响应的 Allow 头列出了它回应的方法。

API 返回This endpoint does not support that HTTP method. The Allow header lists the ones it does.

payload_too_large

413

请求体超过该端点接受的大小。details.limit_bytes 给出所应用的上限。

API 返回The request body is larger than this endpoint accepts.

任何端点都可能返回它。

body_too_deep

400

请求体的嵌套层数超过该端点接受的范围。details.limit_depth 给出对整个请求体所应用的嵌套层数上限。

API 返回The request body nests deeper than this endpoint accepts.

哪些端点会返回它

already_exists

409

已存在使用此标识符的资源。

API 返回A resource with this identifier already exists.

哪些端点会返回它

gtin_in_use

409

此 GTIN 属于另一份产品护照。details 提供 passport、product_name 和 role（lead 或 variant）。请使用该护照或改用其他 GTIN。

API 返回This GTIN belongs to another passport. Use that passport or choose a different GTIN.

哪些端点会返回它

variant_limit_reached

422

此护照已达到变体数量上限。details 包含 limit、current 和 requested。如需添加更多变体，请创建第二份护照。此上限与套餐无关。

API 返回This passport has reached its variant limit. Create a second passport to add more.

哪些端点会返回它

variant_review_required

409

此护照包含由助手填写的尺码与颜色。须先由人工审核：读取 GET …/variants/review，然后使用其指纹发布。details 包含 agent_written_count 和审核 URL。

API 返回This passport carries sizes and colours an assistant wrote. A person reviews them first: read the review, then publish with its fingerprint.

哪些端点会返回它

variant_review_changed

409

尺码与颜色在该指纹所对应的审核之后发生了变化。请重新读取审核并使用当前指纹发布。details 包含 agent_written_count。

API 返回The sizes and colours changed after the review this fingerprint names. Read the review again and publish with its current fingerprint.

哪些端点会返回它

precondition_failed

412

资源已发生改动——可能在您提供的版本之后，也可能在您的请求处理期间。我们报告的 current_version 是我们读取到的版本，未必是当前已存储的版本——请重新读取护照，而不要据此推算。

API 返回The resource changed since the version you supplied.

哪些端点会返回它

resource_busy

409

另一个请求正在修改该资源。请按 Retry-After 响应头给出的时间等待后重试。

API 返回Another request is modifying this resource. Wait for the Retry-After header, then retry.

哪些端点会返回它

gtin_required

422

该护照必须先有 GTIN 才能发布。

API 返回A GTIN is required before this passport can be published.

哪些端点会返回它

not_trashed

409

只有已移入回收站的护照才能恢复。

API 返回Only a trashed passport can be restored.

哪些端点会返回它

publish_limit_reached

402

该组织已用完其套餐允许的全部发布名额。

API 返回This organization has used every publish slot its plan allows.

哪些端点会返回它

unit_limit_reached

402

添加这些单元将使该组织超出其在本服务期内可添加的电池单元数量。details 包含 limit、current、requested、bought_remaining 和 plan_year_ends。

API 返回Adding these units would take the organization over the battery units it can add this plan year. details carries limit, current, requested, bought_remaining and plan_year_ends.

哪些端点会返回它

document_missing

422

某个必填字段只能由一份已不再附加的文档来满足。

API 返回A required field is satisfied only by a document that is no longer attached.

哪些端点会返回它

document_feeds_extraction

409

此文档记录了产品护照各项数值的来源，因此在该护照存在期间会一直保留。未解除任何关联。

API 返回This document is the record of where a passport’s values came from, so it stays while that passport exists. Nothing was detached.

哪些端点会返回它

document_feeds_reading

409

此文档为已记录的电池数值提供依据。只要相关电池记录仍存在，就无法删除。打开电池型号查看这些记录。

API 返回This document supports recorded battery values and cannot be deleted while those battery records exist. Open the battery model to review those records.

invalid_input

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

invalid_observed_on

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

invalid_source

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

invalid_field

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

invalid_note

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

invalid_value

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

invalid_document_id

400

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

unit_status_required

400

此电池已有状态。请选择另一状态，不要清除状态。

API 返回This battery already has a status. Choose a status instead of clearing it.

哪些端点会返回它

unit_status_transition_forbidden

409

电池切换为其他状态后无法恢复为“原始”，进入“废弃”状态后也无法再更改状态。

API 返回This battery’s status cannot return to Original or change after Waste.

哪些端点会返回它

unit_status_history_conflict

409

此状态与电池的已记录历史冲突。请检查日期和状态。

API 返回This status would conflict with the battery’s recorded history. Check the date and status.

哪些端点会返回它

unit_reading_document_unavailable

400

不存在该资源。

API 返回No such resource.

哪些端点会返回它

delegation_required

403

申报需要一份生效中的委托授权，并在调用时向门户核验。

API 返回Filing requires an active delegation, verified against the portal at call time.

哪些端点会返回它

attestation_required

403

此操作需要品牌方一位具名人员作出的确认声明。

API 返回This operation requires an attestation accepted by a named person at the brand.

哪些端点会返回它

test_mode_refused

403

测试模式的凭据无法执行此操作。

API 返回Test-mode credentials cannot perform this operation.

哪些端点会返回它

example_passport_not_fileable

409

演示空间中的演示护照无法提交。

API 返回Example passports from the Playground cannot be filed.

哪些端点会返回它

human_approval_required

202

连接器请求发布。组织中的人员必须批准，并且未发布任何内容。

API 返回A person at your organization must approve this publish. The request was recorded and is waiting for them — give them the link in `details.review_url`. Nothing has been published.

connector_writes_drafts_only

409

代理连接器只能直接修改草稿。对于公众已经能看到的护照，它会发送一项提案，由人员批准。

API 返回This product is already visible to the public, so an assistant cannot change it directly. To change its fields, or the file behind a field, use propose_changes; a person approves the proposal before the public page changes. For anything else, give a person the editor link in `details.review_url`.

哪些端点会返回它

proposal_requires_assistant

403

只有通过 PassportCraft 连接的助手才能提出更改建议。此密钥可以直接修改护照。

API 返回Only an assistant connected through PassportCraft can propose a change. This key can change the passport directly.

哪些端点会返回它

no_changes

422

该提案中的内容与护照当前已有的内容完全一致。

API 返回Nothing in the proposal differs from what the passport already holds.

哪些端点会返回它

unit_status_not_allowed

422

请选择详细信息中列出的五种允许的电池状态之一。

API 返回Choose one of the five permitted battery statuses in `details.allowed`, or leave the status empty.

portal_unavailable

502

法国门户未能及时响应。您的申报可能已被记录，也可能没有。请使用新的 Idempotency-Key 重新发送请求，不会重复申报。重复使用同一个键只会再次返回此错误。

API 返回The French affichage portal did not answer. If the declaration had already been sent, it may still have been recorded — check the passport before filing it again.

哪些端点会返回它

storage_unavailable

503

我们无法确认已上传的文件是否存在于存储中，因此未发布任何内容。您的请求本身没有问题，请在 Retry-After 响应头给出的等待时间之后重试。

API 返回We could not confirm whether the uploaded files are in storage, so nothing was published. Nothing is wrong with your request — retry after the delay in the Retry-After header.

哪些端点会返回它

entitlement_unavailable

503

我们无法确认该组织的使用权限，因此未提交任何内容。这并非对订阅方案的判定，请在 Retry-After 响应头给出的等待时间之后重试。

API 返回We could not confirm this organization’s entitlement, so nothing was filed. This is not a statement about the plan — retry after the delay in the Retry-After header.

哪些端点会返回它

scope_exceeds_key

422

该授权请求了密钥在其所属组织中并不具备的作用域。对客户的授权永远不会超出密钥自身的授权。

API 返回A grant cannot carry a scope the key does not hold on its own organization

哪些端点会返回它

france_mandate_required

403

目前尚不能为该客户授予 filings:write。须先由您组织中的一位人员在该客户的工作区内确认：您持有该客户的书面授权，可代其在法国提交申报。

API 返回filings:write needs the client's written authorisation, affirmed in its workspace, before it can be granted

哪些端点会返回它

grantor_not_seated

403

创建本次调用所用密钥的人员，已不再在该客户的工作区中占有席位，因此无法记录由谁作出这项授权。请在设置中创建新的密钥。

API 返回The person who created this key no longer holds a seat in this organization

哪些端点会返回它

key_not_grantable

409

key_id 所指的密钥已被吊销、已过期、正在被替换，或属于某个助手连接。处于以上任何一种情况的密钥都不能被授权。

API 返回This key cannot be granted: it is revoked, expired, being replaced, or an assistant connection

哪些端点会返回它

grant_conflict

409

该密钥在此处已持有一项作用域不同的授权。请先吊销这项授权，再按所需的作用域重新授权。

API 返回This key already holds a grant here with different scopes; revoke it, then grant again

哪些端点会返回它

live_key_playground_only

403

您的任何客户都没有使用付费的 Pro 或 Scale 套餐，因此此正式密钥只能访问您的演示空间。它不能获得访问客户的权限。仍可访问某个客户的正式密钥无法轮换。测试密钥仍可访问您的客户。

API 返回This live key acts on your Playground only. It can act on a client once one of your clients is on a paid Pro or Scale plan.

哪些端点会返回它

rate_limited

429

请求过于频繁。

API 返回Too many requests in a short time. Wait a moment, then try again.

任何端点都可能返回它。

internal_error

500

我们这边出了问题。

API 返回Something went wrong on our side.

任何端点都可能返回它。

configuration_error

500

服务配置有误。这不是您的请求的问题。

API 返回The service is misconfigured. This is not a problem with your request.

任何端点都可能返回它。

PassportCraft 应用返回的拒绝

已登录的应用会调用自身的接口，这些接口以下面列出的错误码拒绝请求。它们不属于 /v1 契约，随时可能变化。之所以在此列出，是为了让您在应用中看到的提示信息，或一篇帮助文章，有具体的说明可以指向。

billing_managed_by_partner

该工作区的合作伙伴负责管理其账单。结账、账单门户和方案变更都会以此错误码被拒绝。

API 返回Billing for this workspace is managed by the partner that pays for it

partner_role_fixed

此人是该工作区合作伙伴的员工。合作伙伴决定其在此处的权限，您无法更改。该工作区自身的所有者或管理员可以将其移除。

API 返回The partner sets what its staff can do in this workspace.

home_members_only

只有工作区自身的所有者或管理员才能执行此操作，例如接受、拒绝或终止合作伙伴关系。无论角色是什么，合作伙伴的员工都不能执行此操作。只有当密钥由其所属合作伙伴的员工在此工作区中创建，且只对此工作区生效时，他们才能轮换该密钥。

API 返回Only the workspace's own owner or administrator can do this

client_already_linked

该工作区已经有合作伙伴，或者有一个尚未回应的合作伙伴请求。

API 返回This workspace already has a partner, or a request it has not answered

partner_chain_not_allowed

该工作区已经在管理客户，或已由合作伙伴管理。一个组织可以是合作伙伴，也可以是合作伙伴的客户，但不能同时具备这两种身份，因此无法建立此管理关系。

API 返回An organization can manage clients or be managed by a partner, not both

not_a_partner

X-Organization 中指定的组织不管理任何客户。

API 返回This organization does not manage clients

partner_staff_only

只有负责管理的合作伙伴自己的员工才能执行此操作，例如确认客户为法国“环境成本”（coût environnemental）申报出具的书面授权。

API 返回Only the partner's staff can do this

same_organization

一个组织不能管理自己。

API 返回An organization cannot manage itself

organization_not_found

没有工作区与提供的地址或电子邮箱匹配。

API 返回Organization not found

organization_header_required

请求未指定工作区。请在 X-Organization 请求头中发送工作区的 slug。

API 返回The X-Organization header is required

organization_not_a_member

登录用户不是 X-Organization 中指定工作区的成员。

API 返回Not a member of this organization

continuity_pending

合作伙伴支付的方案仍在生效。该工作区的账单将在付款所覆盖的到期日发生变化。

API 返回The current plan runs to the date it was paid to; billing for this workspace changes after that

partner_terms_missing

该合作伙伴尚未记录任何账单条款，因此暂时无法在其账户下开通方案。

API 返回This partner has no billing terms recorded

partner_customer_missing

该合作伙伴尚无支付账户。

API 返回This partner has no payment account yet

partner_card_missing

该合作伙伴未登记付款方式，需在自己的“账单”页面添加。

API 返回This partner organization has no payment method on file

client_already_subscribed

该工作区已经为自己的订阅付费。

API 返回This workspace already has its own subscription

plan_below_current

所选方案低于该工作区当前所用的方案。

API 返回That plan is smaller than the one this workspace is on

continuity_not_available

没有可为该工作区延续的、由前一个合作伙伴支付的付费期。

API 返回There is nothing to continue on this workspace

yearly_not_accepted

只有在合作伙伴确认该客户的年度计费周期后，客户方案才会开通。

API 返回The partner has not confirmed the yearly billing period for this client; record its confirmation before opening the plan.

stripe_refused

支付服务商拒绝了此请求。

API 返回Stripe refused the request

payment_pending

付款结果尚未确定。请查询已有请求的状态，不要创建另一位客户或再次提交付款。

API 返回The payment result is not yet known. Check its status before starting another payment.

price_changed

已确认的价格与最新预览不一致。请核对更新后的价格再提交。尚未创建客户。

API 返回The price changed. Review the current amount before creating the client.

price_unavailable

价格预览暂不可用。请先重新加载预览，再创建客户。尚未创建客户。

API 返回The price is unavailable. No client was created. Try the review again later.

price_changed_after_create

客户已创建并使用免费版。价格发生变化，未付款的支付尝试已安全关闭。请联系支持团队启用套餐，不要重复创建客户。

API 返回The client was added on Free. The reviewed payment did not proceed. Contact support to activate the plan.

creation_token_invalid

此次核对与用户、工作区或客户信息不匹配。请重新核对正确信息。如果已提交创建请求且结果未知，请联系支持团队，不要重新开始。

API 返回This creation review is invalid. If creation has already started, check its status or contact support.

creation_token_expired

创建授权已过期。请先查询任何已有创建请求；如果尚未提交请求，请重新核对付款。

API 返回This creation review expired. Check any existing operation before reviewing a new creation.

creation_operation_expired

此创建请求保留的状态已不可用。请先联系支持团队再进行其他操作，不要重复创建客户。

API 返回This operation status is no longer available. Contact support before creating another client.

creation_conflict

此创建请求已绑定其他信息。请查询原请求或联系支持团队，不要发起新的创建。

API 返回This operation belongs to different creation details. Check the original operation or contact support.

creation_unavailable

创建前核对暂不可用，请稍后重试。如果创建请求的结果未知，请查询其状态，不要再次提交。

API 返回Creation review is unavailable. Try again later; check the status of any creation already started.

client_creation_undone

未创建任何内容，也未产生任何扣款。请核对付款信息后重试。

API 返回The client could not be created and nothing was charged. Review the payment again.

client_vat_unverified

工作区只有填写了所在国家，才能接管账单。

API 返回Give the workspace's country before you add a card.

client_authority_required

只有在合作伙伴确认客户已授权其代表客户接受服务条款和数据处理协议后，才会创建客户工作区。

API 返回The client's authority confirmation is missing. Tick the confirmation on the review step, then create the client.

client_details_required

创建客户工作区需要客户的法定名称以及用于发送通知的电子邮箱地址。

API 返回The client's legal name and an email address for notices are required.

terms_acceptance_required

工作区只有在同时接受当前的服务条款和数据处理协议后，才能接受合作伙伴的请求或购买付费方案。

API 返回Accept the current Terms of Service and Data Processing Agreement together with the request.

client_not_managed

所列组织不是您的组织管理的客户。

API 返回That organization is not a client your organization manages

keys_admin_partner_only

keys:admin 只能授予属于管理客户的组织的密钥。

API 返回keys:admin can only be granted on the own keys of an organization that manages clients

grant_not_found

没有其他组织的密钥以该 id 持有对此工作区的访问权限。

API 返回No key from another organization holds a grant here under that id

partner_agreement_required

该合作伙伴尚未接受当前的合作伙伴协议，或其协议已终止。合作伙伴可在其合作伙伴条款页面接受协议。

API 返回This partner has not accepted the current partner agreement, or its agreement has ended. It must accept the agreement on its Partner terms page first.

agreement_unpublished

合作伙伴协议尚未发布，因此无法接受。

API 返回The partner agreement is not published yet

agreement_text_changed

页面打开期间协议已发生变更。请重新加载合作伙伴条款页面，并接受显示的版本。

API 返回The agreement changed after it was shown. Reload the page and accept the version shown.

discount_unavailable

我们无法读取合作伙伴优惠，因此未接受任何内容。请重试。

API 返回The partner discount could not be read. Nothing was accepted; try again.

partner_admin_access_fixed

此人是合作伙伴的所有者或管理员，因此可为合作伙伴管理的所有客户工作。所有者始终为所有客户工作。如需选择管理员负责的客户，请先将其在合作伙伴团队中的角色改为编辑者或查看者。

API 返回Owners and administrators work on every client. To limit an administrator's clients, make them an editor or viewer on your Team page first.

seat_removed_by_client

客户已将此人从其工作区移除。合作伙伴无法重新添加。客户的所有者或管理员可以在客户的团队页面再次允许此人加入。

API 返回The client removed this person from its workspace. Only the client can allow them again.

partner_staff_managed_by_partner

合作伙伴的员工不能在客户的工作区中互相移除。合作伙伴在自己的团队页面为员工选择客户。客户自己的所有者或管理员可以移除任何人。

API 返回Only this workspace's own owner or administrators can remove a partner's staff here. The partner can change its staff's clients from its own Team page.

member_not_found

此人已不在团队中。请重新加载列表后重试。

API 返回Member not found

playground_has_no_plans

该工作区是合作伙伴的演示空间。其限额固定，没有可购买的方案。因此，结账、方案变更和购买序列号都会以此错误码被拒绝。合作伙伴在添加客户时为该客户购买方案。

API 返回Your Playground has fixed limits and no plan to buy. To buy a plan for a client, use Add client on the Clients page. Client billing, under Partner settings, shows what you pay.

client_not_partner_paid

该合作伙伴不为此客户的方案付费，该合作伙伴关系即将结束，或该客户的方案已设为取消。将该客户升级到更高级的方案和为其添加序列号都会以此错误码被拒绝。

API 返回Your organization does not pay for this client's plan, or the client is leaving or set to cancel.

partner_agreement_ended

合作伙伴协议已终止，因此该合作伙伴无法再将客户升级到更高级的方案。

API 返回Your partner agreement has ended, so a client's plan cannot move to a larger plan.

校验规则

这些是产品护照数据本身可能违反的规则，适用于所有类别。规则名称会出现在三个位置：422 响应的 error.details.issues 之中、校验端点 200 响应的 issues 之中，以及批量导入行的 error.detail.issues 之中。创建、更新与导入只会因标记为保存时同样会被拒绝的那两条而拒绝 data 中的值；此外，创建还会针对本服务不支持的类别返回 required。其余规则来自发布或校验端点。发布会返回完整列表，其中也包含提示性规则，因此会列出并非拒绝原因的规则。请根据规则名称分支处理，不要依赖提示文字。

required

阻止发布

该字段在此类别中为必填，但收到的是空值、缺失或空列表。在本服务不支持的类别下创建护照，同样会返回该规则，其 JSON Pointer 为 /category。

如何修正请提交一个值。如果 url 字段用于佐证文件，改为上传该文件同样可以满足要求。

type_array

阻止发布保存时同样会被拒绝

该字段存放列表，但收到的值不是列表，通常是把列表写成了 JSON 字符串。

如何修正请提交真正的 JSON 数组，而不是包含数组的字符串。

type_array_items

阻止发布保存时同样会被拒绝

该字段存放纯文本列表，但至少有一项是对象、数字或布尔值。

如何修正请将每一项都提交为字符串。有此要求的字段会在类别架构中带有 item_type。

type_number

阻止发布

该字段存放数字，但收到的值不是数字，通常是把数字写成了字符串。

如何修正请提交不带引号的 JSON 数字。

type_text

阻止发布

该字段保存文本，而所提供的值不是文本——通常是向类别架构声明为文本的字段，或向同时接受自填答案的选择字段发送了数字、布尔值或列表。

如何修正请以 JSON 字符串形式发送该值。请查阅类别架构中该字段的 type。提供 other 选项的 select 字段同样以字符串形式接受自填答案。

number_min

阻止发布

该值小于此字段允许的最小数字。

如何修正请查看类别架构中该字段的 min，并提交不小于该值的数字。

number_max

阻止发布

该值大于此字段允许的最大数字。

如何修正请查看类别架构中该字段的 max，并提交不大于该值的数字。

format_date

阻止发布

该值不是有效的 ISO 8601 日期。不存在的日期（例如 2025-02-30）在此会被拒绝。

如何修正请提交 YYYY-MM-DD，或以 Z 结尾的 UTC 时区 ISO 8601 时间戳。若时区偏移使该时间戳落到另一个日期，将被拒绝。

format_url

阻止发布

该值不是有效的网址。

如何修正请提交以 https:// 或 http:// 开头的完整网址。

invalid_option

阻止发布

该字段只接受固定的取值范围，而收到的值不在其中。提供 other 选项的字段除外：这类字段会直接保存自由文本。

如何修正请查看类别架构中该字段的 options，并提交其中列出的 value 之一。

format_gtin

阻止发布

该 GTIN 不是真实编码：它以空字符串送达、含有非数字字符、长度不正确、校验位不匹配，或者本身就是文档示例。

如何修正请提交 GS1 分配给您的 GTIN-8、GTIN-12、GTIN-13 或 GTIN-14。提示文字会说明属于哪一种问题。

format_eori

阻止发布

EORI 号码不符合该字段接受的格式。

如何修正请提交两位大写国家字母，后接 1 至 15 位大写字母或数字。小写会被拒绝。

format_country_code

阻止发布

国家不是两位大写字母。诸如 de 的小写代码会被拒绝。

如何修正请提交大写的 ISO 3166-1 alpha-2 代码，例如 DE。

format_commodity_code

提示

商品编码不符合 HS、CN 或 TARIC 格式。

如何修正请提交 6 位、8 位或 10 位数字。也可以保留现有取值，直接发布该护照。

format_email

阻止发布

该值不是有效的电子邮件地址。

如何修正请提交完整的地址。

category_exists

阻止发布

该护照指定的产品类别不在本 API 的服务范围内。

如何修正改发其他类别无法解决：已保存的护照指定了本服务不再支持的类别。请在类别列表端点返回的类别下重新创建。

另有三类内容也会带上规则名称。产品类别会追加自己的规则，这类规则同时读取多个字段，例如材料百分比之和必须为 100。端点也以同样的方式报告请求本身的问题，使用 not_writable 这类名称。发布检查还会把 required 用在发布所需的值上，例如 GTIN，而该字段在类别本身并非必填。以上各种情况，响应中的提示文字都会说明该规则。

护照数据限制

护照数据的大小有上限。若某次创建、更新或提案会使数据超出其中一项限制，请求会被拒绝，返回 422 validation_failed。若我们的检查发现数据超出某项限制，校验端点同样返回 422 validation_failed。接近字节上限时，即使该检查已接受这些数据，数据库在保存时仍可能拒绝它们。error.details.issues 下的一个问题项会指明规则。若某个批量导入行会出现同样的情况，该行会以 field_wrong_shape 失败。同一个问题项位于该行的 error.detail.issues 之下。每个问题项都包含 source.pointer、rule、limit 和 received。请根据规则分支处理，不要依赖提示文字。

source.pointer 指向包含该问题的顶层字段，按更改生效之后的护照来判断。更新、提案或向校验端点发送请求时，它可能是请求中没有发送的字段。创建、更新以及向校验端点发送请求时，JSON Pointer 从 /data 开始，提案从 /fields 开始。批量导入行从 /rows/<n>/data 开始，其中 n 是该行在导入中的索引。涉及整份护照的规则，例如 too_many_fields，只指向这个起点。

received 对 list_too_long 和 too_many_entries 统计列表项数，对 too_many_fields 统计顶层字段数。对 data_too_large，它是以字节计的大小。若由数据库发现这种超限，它统计的是已存储的 JSON 文本，可能比所发送的 JSON 略大。对 number_out_of_range，limit 和 received 为 null，因为响应从不重复该数字。

list_too_long

护照数据中的某个列表包含超过 500 项。列表无论位于何处都会计入，包括另一个列表或某个对象内部的列表。

如何修正请将 source.pointer 所指字段中最长的列表缩减到最多 500 项。PATCH 会整体替换一个列表，因此请发送缩短后的列表。

API 返回"limit": 500

too_many_entries

护照数据中的所有列表合计包含超过 5,000 项。每个列表都计入，包括嵌套在其他列表中的列表。

如何修正请删除列表项，直到所有列表合计不超过 5,000 项。source.pointer 指向列表项最多的字段。

API 返回"limit": 5000

data_too_large

护照数据以 JSON 文本计超过 262,144 字节。字节按 UTF-8 计数，因此一个字符最多可占四个字节。

如何修正请缩短 source.pointer 所指的最大字段中的文本，或删除护照不需要的值。

API 返回"limit": 262144

number_out_of_range

护照数据中的某个数字超出护照接受的范围。零可以接受。其他数字不计正负号时，必须不小于 1e-30 且小于 1e30。

如何修正请找到 source.pointer 所指字段中的数字，改为发送该范围内的数字。

API 返回"limit": null

too_many_fields

护照数据的顶层包含超过 1,000 个字段。

如何修正请删除护照不需要的顶层字段。类别架构列出了各个类别所定义的字段。

API 返回"limit": 1000

警告

警告不是拒绝。它伴随 200 响应出现在一次成功的调用上，用来指出值得跟进处理的情况。

environmental_claim_detected

200

该护照含有环境声明，见于其文字表述，或见于品牌方标记为环境信息的字段。发布已经成功，护照也已上线。自 2026 年 9 月 27 日起，欧盟指令 (EU) 2024/825 要求将产品投放市场的经营者持有此类声明的证明材料。