Errors — PassportCraft API

Errors

Every failure carries a stable code. Branch on the code and never on the message: the wording can change at any time, the code will not.

Paths, methods, scopes, field names, error codes and validation rule names are published in English, because English is the language of the interface itself — they are what a caller types or matches on. So is every code sample and JSON payload, and the exact sentence an error response carries: /v1 does not read Accept-Language, so translating what the API literally sends would misdescribe it. Everything written about them follows the language of this page.

The error envelope

Every non-2xx response has the same shape. documentation_url points straight at the entry below, and request_id is the value to quote in a support request. details carries machine-readable context — for a refused body that is issues, each one a JSON Pointer at the field that was wrong.

Response

{
  "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" }
      ]
    }
  }
}

Codes

Each code is linked from the response that carries it, so this page is usually reached at the entry that is needed.

invalid_key

401

The API key provided is not valid.

API returnsThe API key provided is not valid.

Any endpoint can return this.

key_revoked

401

This API key has been revoked.

API returnsThis API key has been revoked.

Any endpoint can return this.

key_expired

401

This API key has expired.

API returnsThis API key has expired.

Any endpoint can return this.

key_rotated

401

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

API returnsThis API key was replaced by a rotation and its overlap window has closed.

Any endpoint can return this.

mode_mismatch

400

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

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

Any endpoint can return this.

insufficient_scope

403

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

API returnsThis credential does not carry the scope required for this operation.

Which endpoints return this

organization_not_found_or_not_granted

404

No such organization, or this key has no grant on it. A grant ends when someone revokes it or when the organization's arrangement with its partner ends; the organization then leaves GET /organizations.

API returnsNo such organization.

Which endpoints return this

resource_not_found

404

No such resource.

API returnsNo such resource.

Which endpoints return this

wildcard_not_supported

400

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

API returnsThe "-" organization wildcard is reserved and not yet supported.

Which endpoints return this

validation_failed

422

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

invalid_request

400

The request could not be understood.

API returnsThe request could not be understood.

Any endpoint can return this.

method_not_allowed

405

The endpoint exists but does not answer this HTTP method. The Allow header on the refusal lists the methods it does answer.

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

payload_too_large

413

The request body is larger than this endpoint accepts. details.limit_bytes carries the ceiling that was applied.

API returnsThe request body is larger than this endpoint accepts.

Any endpoint can return this.

unsupported_media_type

415

The request body did not arrive as application/json.

API returnsThe request body must be sent as application/json.

Which endpoints return this

idempotency_conflict

409

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

API returnsThis Idempotency-Key was already used with a different request body.

Which endpoints return this

already_exists

409

A resource with this identifier already exists.

API returnsA resource with this identifier already exists.

Which endpoints return this

gtin_in_use

409

This GTIN belongs to another passport. details names its passport, product_name and role (lead or variant). Use that passport or choose a different GTIN.

API returnsThis GTIN belongs to another passport. Use that passport or choose a different GTIN.

Which endpoints return this

variant_limit_reached

422

This passport has reached its variant limit. details carries limit, current and requested. Create a second passport to add more; the limit does not depend on the plan.

API returnsThis passport has reached its variant limit. Create a second passport to add more.

Which endpoints return this

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

variant_review_required

409

This passport carries sizes and colours an assistant wrote. A person reviews them first: read GET …/variants/review, then publish with its fingerprint. details carries agent_written_count and the review URL.

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

Which endpoints return this

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

variant_review_changed

409

The sizes and colours changed after the review this fingerprint names. Read the review again and publish with its current fingerprint. details carries agent_written_count.

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

Which endpoints return this

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

precondition_failed

412

The resource changed — either since the version you supplied, or while your request was in flight. The current_version we report is the version we read, not necessarily the one now stored — re-read the passport rather than computing from it.

API returnsThe resource changed since the version you supplied.

Which endpoints return this

resource_busy

409

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

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

Which endpoints return this

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

cursor_invalid

400

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

API returnsThe pagination cursor is invalid, expired, or was sent with different filters.

Which endpoints return this

no_subscription

402

This organization has no active subscription.

API returnsThis organization has no active subscription.

Which endpoints return this

plan_required

402

This organization’s plan does not include this operation.

API returnsThis organization’s plan does not include this operation.

Which endpoints return this

payment_overdue

402

Publishing is disabled while payment is overdue.

API returnsPublishing is disabled while payment is overdue.

Which endpoints return this

gtin_required

422

A GTIN is required before this passport can be published.

API returnsA GTIN is required before this passport can be published.

Which endpoints return this

wrong_status

409

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

API returnsThe passport is not in a status that allows this operation.

Which endpoints return this

not_trashed

409

Only a trashed passport can be restored.

API returnsOnly a trashed passport can be restored.

Which endpoints return this

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

publish_limit_reached

402

This organization has used every publish slot its plan allows.

API returnsThis organization has used every publish slot its plan allows.

Which endpoints return this

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

unit_limit_reached

402

This passport carries more units than the plan allows.

API returnsThis passport carries more units than the plan allows.

Which endpoints return this

document_missing

422

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

API returnsA required field is satisfied only by a document that is no longer attached.

Which endpoints return this

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

document_feeds_extraction

409

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

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

Which endpoints return this

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

document_feeds_reading

409

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

API returnsThis 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

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_observed_on

400

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_source

400

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_field

400

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

invalid_note

400

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_value

400

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

invalid_document_id

400

The request body failed validation.

API returnsThe request body failed validation.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_status_required

400

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

API returnsThis battery already has a status. Choose a status instead of clearing it.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_status_transition_forbidden

409

A battery cannot return to Original after another status, or change status after Waste.

API returnsThis battery’s status cannot return to Original or change after Waste.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_status_history_conflict

409

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

API returnsThis status would conflict with the battery’s recorded history. Check the date and status.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

unit_reading_document_unavailable

400

No such resource.

API returnsNo such resource.

Which endpoints return this

post/organizations/{organization}/passports/{id}/units/{unitId}/readings

delegation_required

403

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

API returnsFiling requires an active delegation, verified against the portal at call time.

Which endpoints return this

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

attestation_required

403

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

API returnsThis operation requires an attestation accepted by a named person at the brand.

Which endpoints return this

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

test_mode_refused

403

Test-mode credentials cannot perform this operation.

API returnsTest-mode credentials cannot perform this operation.

Which endpoints return this

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

human_approval_required

202

The connector asked to publish. A person at the organization must approve it, and nothing was published.

API returnsA 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

The agent connector may only change a draft. A passport the public can already see needs a person.

API returnsThis 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`.

Which endpoints return this

unit_status_not_allowed

422

Choose one of the five permitted battery statuses named in the details.

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

portal_unavailable

502

The French portal did not answer in time. Your declaration may or may not have been recorded. Send the request again with a new Idempotency-Key — nothing is declared twice. Reusing the same key only returns this error again.

API returnsThe 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.

Which endpoints return this

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

storage_unavailable

503

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.

API returnsWe 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.

Which endpoints return this

entitlement_unavailable

503

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.

API returnsWe 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.

Which endpoints return this

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

scope_exceeds_key

422

The grant asks for a scope the key does not hold on its own organization. A client's grant never exceeds the key's own.

API returnsA grant cannot carry a scope the key does not hold on its own organization

Which endpoints return this

post/organizations/{organization}/grants

france_mandate_required

403

filings:write cannot be granted for this client yet. A person at your organization must first confirm, in the client's workspace, that you hold its written authorisation to file in France.

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

Which endpoints return this

post/organizations/{organization}/grants

grantor_not_seated

403

The person who created the calling key no longer holds a seat in this client's workspace, so nobody can be recorded as giving the grant. Create a new key in Settings.

API returnsThe person who created this key no longer holds a seat in this organization

Which endpoints return this

post/organizations/{organization}/grants

key_not_grantable

409

The key named in key_id is revoked, expired, being replaced, or an assistant connection. None of these can be granted.

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

Which endpoints return this

post/organizations/{organization}/grants

grant_conflict

409

The key already holds a grant here with different scopes. Revoke it, then grant again with the scopes you want.

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

Which endpoints return this

post/organizations/{organization}/grants

rate_limited

429

Too many requests.

API returnsToo many requests in a short time. Wait a moment, then try again.

Any endpoint can return this.

internal_error

500

Something went wrong on our side.

API returnsSomething went wrong on our side.

Any endpoint can return this.

configuration_error

500

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

API returnsThe service is misconfigured. This is not a problem with your request.

Any endpoint can return this.

Refusals from the PassportCraft app

The signed-in app calls its own routes, and those routes refuse with the codes below. They are not part of the /v1 contract and may change. They are listed so that a message you see in the app, or a help article, has somewhere to point.

billing_managed_by_partner

The workspace's partner manages its billing. Checkout, the billing portal and plan changes all refuse with this code.

API returnsBilling for this workspace is managed by the partner that pays for it

partner_role_fixed

This person works for the workspace's partner. Their role here follows their role at the partner and cannot be changed; an owner or admin can remove them.

API returnsA partner member's role follows their role at the partner

home_members_only

Only the workspace's own owner or administrators can do this, for example accept, decline or stop a partner. A partner's staff cannot, whatever their role. They can rotate a key only when their partner's staff made it in this workspace and it acts on this workspace alone.

API returnsOnly the workspace's own owner or administrator can do this

client_already_linked

This workspace already has a partner, or a partner's request it has not answered yet.

API returnsThis workspace already has a partner, or a request it has not answered

partner_chain_not_allowed

The workspace already manages clients, or a partner already manages it. An organization can be a partner or a partner's client, never both, so this arrangement cannot start.

API returnsAn organization can manage clients or be managed by a partner, not both

not_a_partner

The organization named in X-Organization does not manage any client.

API returnsThis organization does not manage clients

partner_staff_only

Only the managing partner's own staff can do this, such as confirming a client's written authorisation for France filings.

API returnsOnly the partner's staff can do this

link_not_found

No partner arrangement with that id exists for this workspace.

API returnsLink not found

link_not_pending

That request has already been answered.

API returnsThis request has already been answered

link_not_accepted

The partner arrangement is not active: it is still waiting for an answer, or it has ended.

API returnsThis link is not active

same_organization

An organization cannot manage itself.

API returnsAn organization cannot manage itself

organization_not_found

No workspace matches the address or email given.

API returnsOrganization not found

organization_header_required

The request did not name a workspace. Send the workspace's slug in the X-Organization header.

API returnsThe X-Organization header is required

organization_not_a_member

The signed-in person is not a member of the workspace named in X-Organization.

API returnsNot a member of this organization

continuity_pending

The plan the partner paid for is still running. Billing for this workspace changes on the date it was paid to.

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

partner_terms_missing

No billing terms are recorded for this partner yet, so no plan can be opened on its account.

API returnsThis partner has no billing terms recorded

partner_customer_missing

The partner has no payment account yet.

API returnsThis partner has no payment account yet

partner_card_missing

The partner has no payment method on file. It adds one on its own Billing page.

API returnsThis partner organization has no payment method on file

client_already_subscribed

This workspace already pays for its own subscription.

API returnsThis workspace already has its own subscription

plan_below_current

The plan chosen is smaller than the one this workspace is on.

API returnsThat plan is smaller than the one this workspace is on

continuity_not_available

There is no paid period from a former partner to carry on for this workspace.

API returnsThere is nothing to continue on this workspace

yearly_not_accepted

A yearly plan on a partner's account needs the partner's written acceptance of the annual term recorded first.

API returnsThis partner has not accepted the annual term in writing; record it before opening a yearly plan

stripe_refused

The payment provider refused the request.

API returnsStripe refused the request

payment_pending

The payment outcome is not yet known. Check the existing request’s status; do not create another client or submit another payment.

API returnsThe payment result is not yet known. Check its status before starting another payment.

price_changed

The confirmed price differs from the latest preview. Review the updated price before submitting again. No client was created.

API returnsThe price changed. Review the current amount before creating the client.

price_unavailable

The price preview is unavailable. Retry the preview before creating the client. No client was created.

API returnsThe price is unavailable. No client was created. Try the review again later.

price_changed_after_create

The client was created on Free. The price changed and the unpaid payment attempt was safely closed. Contact support to activate its plan; do not create the client again.

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

creation_token_invalid

This review does not match the user, workspace or client details. Review the correct details again. If a creation request was already submitted and its outcome is unknown, contact support instead of starting again.

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

creation_token_expired

The creation authorization has expired. Check any existing creation request first; if none was submitted, review the payment again.

API returnsThis creation review expired. Check any existing operation before reviewing a new creation.

creation_operation_expired

The retained status of this creation request is no longer available. Contact support before taking further action; do not create the client again.

API returnsThis operation status is no longer available. Contact support before creating another client.

creation_conflict

This creation request is already tied to different details. Check the original request or contact support; do not start another creation.

API returnsThis operation belongs to different creation details. Check the original operation or contact support.

creation_unavailable

The creation review is unavailable. Try the review later. If a creation request’s outcome is unknown, check its status instead of submitting it again.

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

client_not_managed

The organization named is not a client your organization manages.

API returnsThat organization is not a client your organization manages

keys_admin_partner_only

keys:admin can only be given to a key that belongs to an organization that manages clients.

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

grant_not_found

No key from another organization holds access to this workspace under that id.

API returnsNo key from another organization holds a grant here under that id

Validation rules

These are the rules the passport data itself can break, in any category. A rule name reaches you in three places: under error.details.issues in a 422, under issues in the 200 from the validate endpoint, and under error.detail.issues on a bulk-import row. Create, update and import refuse a value inside data only for the two marked as refused on save — though create also returns required for a category it does not serve. The rest arrive from publish or from the validate endpoint. Publish returns the full list, advisories included, so it names rules that did not cause the refusal. Branch on the rule, never on the message.

required

blocks publish

The field is required for this category and arrived empty, absent, or as an empty list. Creating a passport under a category we do not serve also returns this rule, on the JSON Pointer /category.

How to fixSend a value. A url field that documents a file is also satisfied by attaching that document instead.

type_array

blocks publishalso refused when you save

The field holds a list, and the value was not one — most often a list sent as a JSON string.

How to fixSend a real JSON array, not a string containing one.

type_array_items

blocks publishalso refused when you save

The field holds a list of plain text values, and at least one entry was an object, a number, or a boolean.

How to fixSend every entry as a string. The field carries item_type in the category schema when it requires this.

type_number

blocks publish

The field holds a number, and the value was not one — most often a number sent as a string.

How to fixSend a JSON number, unquoted.

type_text

blocks publish

The field holds text, and the value was not text — most often a number, a boolean or a list sent for a field the category schema declares as text, or for a choice field that also takes a written-in answer.

How to fixSend the value as a JSON string. Read type on the field in the category schema. A select that offers an other option takes a written-in answer as a string too.

number_min

blocks publish

The value is below the smallest number the field accepts.

How to fixRead min on the field in the category schema, then send a value at or above it.

number_max

blocks publish

The value is above the largest number the field accepts.

How to fixRead max on the field in the category schema, then send a value at or below it.

format_date

blocks publish

The value is not a valid ISO 8601 date. A date that does not exist, such as 2025-02-30, is refused here.

How to fixSend YYYY-MM-DD, or an ISO 8601 timestamp in UTC, ending Z. An offset that puts the timestamp on a different date is refused.

format_url

blocks publish

The value is not a valid URL.

How to fixSend an absolute https:// or http:// URL.

invalid_option

blocks publish

The field accepts a fixed set of values, and the value was not one of them. A field that offers an other option is exempt: it stores free text instead.

How to fixRead options on the field in the category schema, then send one of the value entries it lists.

format_gtin

blocks publish

The GTIN is not a real one: it arrived as an empty string, holds characters that are not digits, has the wrong length, has a check digit that does not match, or is a documentation example.

How to fixSend a GTIN-8, GTIN-12, GTIN-13, or GTIN-14 that GS1 issued to you. The message names which problem it is.

format_eori

blocks publish

The EORI number does not match the format the field accepts.

How to fixSend two uppercase country letters, then 1 to 15 uppercase letters or digits. Lowercase is refused.

format_country_code

blocks publish

The country is not two uppercase letters. A lowercase code such as de is refused.

How to fixSend an uppercase ISO 3166-1 alpha-2 code, such as DE.

format_commodity_code

advisory

The commodity code does not match the HS, CN, or TARIC format.

How to fixSend 6, 8, or 10 digits. You can also publish the passport with the value as it stands.

format_email

blocks publish

The value is not a valid email address.

How to fixSend a complete address.

category_exists

blocks publish

The passport names a product category this API does not serve.

How to fixSending a different category does not clear this one: the stored passport names a category we no longer serve. Recreate it under a category the category list endpoint returns.

Three other things carry a rule name. A product category adds rules of its own, which read several fields together — material percentages that must total 100, for example. An endpoint reports a problem with the request itself the same way, under names such as not_writable. And the publish gate reuses required for a value publishing needs, such as a GTIN, on a field the category itself does not require. In each case the message in the response explains the rule.

Warnings

A warning is not a refusal. It arrives alongside a 200, on a call that succeeded, and names something worth acting on.

environmental_claim_detected

200

The passport carries environmental claims, found in its wording or in fields the brand marked as environmental information. Publishing succeeded and the passport is live. From 27 September 2026, Directive (EU) 2024/825 requires the trader placing the product on the market to hold substantiation for such claims.