错误 — PassportCraft API

错误

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

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

不存在该组织。

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.

哪些端点会返回它

validation_failed

422

请求体未通过校验。

API 返回The request body failed validation.

哪些端点会返回它

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.

任何端点都可能返回它。

unsupported_media_type

415

请求体不是以 application/json 到达的。

API 返回The request body must be sent as application/json.

哪些端点会返回它

idempotency_conflict

409

该 Idempotency-Key 此前已用于另一个不同的请求体。

API 返回This Idempotency-Key was already used with a different request body.

哪些端点会返回它

precondition_failed

412

资源在您提供的版本之后已发生改动。

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.

哪些端点会返回它

delete/organizations/{organization}/passports/{id}/documents/{documentId}

cursor_invalid

400

分页游标无效、已过期，或是与其他筛选条件一起发送的。

API 返回The pagination cursor is invalid, expired, or was sent with different filters.

哪些端点会返回它

no_subscription

402

该组织没有生效中的订阅。

API 返回This organization has no active subscription.

哪些端点会返回它

payment_overdue

402

款项逾期期间，发布功能不可用。

API 返回Publishing is disabled while payment is overdue.

哪些端点会返回它

gtin_required

422

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

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

哪些端点会返回它

wrong_status

409

护照当前所处的状态不允许执行此操作。

API 返回The passport is not in a status that allows this operation.

哪些端点会返回它

not_trashed

409

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

API 返回Only a trashed passport can be restored.

哪些端点会返回它

post/organizations/{organization}/passports/{id}/restore

publish_limit_reached

402

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

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

哪些端点会返回它

post/organizations/{organization}/passports/{id}/publish

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.

哪些端点会返回它

post/organizations/{organization}/passports/{id}/publish

delegation_required

403

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

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

哪些端点会返回它

post/organizations/{organization}/passports/{id}/affichage

attestation_required

403

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

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

哪些端点会返回它

post/organizations/{organization}/passports/{id}/affichage

test_mode_refused

403

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

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

哪些端点会返回它

post/organizations/{organization}/passports/{id}/affichage

portal_unavailable

502

无法连接法国环境成本官方门户，因此未提交任何申报。

API 返回The French affichage portal could not be reached, so nothing was filed.

哪些端点会返回它

post/organizations/{organization}/passports/{id}/affichage

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.

哪些端点会返回它

post/organizations/{organization}/passports/{id}/affichage

rate_limited

429

请求过于频繁。

API 返回Too many requests.

任何端点都可能返回它。

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.

任何端点都可能返回它。

警告

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

environmental_claim_detected

200

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