跳到主要内容

错误

错误

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

路径、方法、作用域、字段名、错误码和校验规则名称一律以英文发布，因为接口本身的语言就是英文——这些正是调用方需要照原样输入或比对的内容。每一段代码示例、每一个 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.

任何端点都可能返回它。

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

该护照下的单元数量已超过套餐允许的上限。

API 返回This passport carries more units than the plan allows.

哪些端点会返回它

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.

哪些端点会返回它

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. A person has to make the change — give them the editor link in `details.review_url`.

哪些端点会返回它

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

哪些端点会返回它

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 返回A partner member's role follows their role at the partner

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 返回This partner has not accepted the annual term in writing; record it before opening a yearly 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_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

校验规则

这些是产品护照数据本身可能违反的规则，适用于所有类别。规则名称会出现在三个位置：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，而该字段在类别本身并非必填。以上各种情况，响应中的提示文字都会说明该规则。

警告

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

environmental_claim_detected

200

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