Erreurs
Erreurs
Chaque échec porte un code stable. Aiguillez-vous sur le code et jamais sur le message : la formulation peut changer à tout moment, le code non.
Les chemins, les méthodes, les portées, les noms de champs et les codes d'erreur sont publiés en anglais, car l'anglais est la langue de l'interface elle-même : c'est ce qu'un appelant saisit ou compare. Il en va de même de chaque exemple de code, de chaque charge utile JSON et de la phrase exacte que porte une réponse d'erreur : /v1 ne lit pas Accept-Language, et traduire ce que l'API envoie réellement en donnerait une description fausse. Tout ce qui est écrit à leur sujet suit la langue de cette page.
L'enveloppe d'erreur
Toute réponse hors 2xx a la même forme. documentation_url pointe directement vers l'entrée correspondante ci-dessous, et request_id est la valeur à citer dans une demande d'assistance. details porte un contexte lisible par machine — pour un corps refusé, ce sont les issues, chacune un JSON Pointer vers le champ en cause.
{
"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
Chaque code est lié depuis la réponse qui le porte : on arrive donc le plus souvent sur cette page directement à l'entrée recherchée.
invalid_key
401Aucune clé active ne correspond à la valeur transmise. Vérifiez qu'elle a été copiée en entier, sans espace ni retour à la ligne.
Réponse de l’APIThe API key provided is not valid.
N'importe quel point de terminaison peut le renvoyer.
key_revoked
401La clé a bien existé, mais elle a été révoquée : elle n'ouvre plus rien et ne peut pas être réactivée. Il faut en créer une nouvelle.
Réponse de l’APIThis API key has been revoked.
N'importe quel point de terminaison peut le renvoyer.
key_expired
401La clé a dépassé la date d'expiration fixée à sa création. Remplacez-la par une clé neuve.
Réponse de l’APIThis API key has expired.
N'importe quel point de terminaison peut le renvoyer.
key_rotated
401La clé a été remplacée lors d'une rotation, et la fenêtre pendant laquelle l'ancienne restait acceptée est close. Passez à la clé issue de la rotation.
Réponse de l’APIThis API key was replaced by a rotation and its overlap window has closed.
N'importe quel point de terminaison peut le renvoyer.
mode_mismatch
400Le préfixe de la clé ne correspond pas à l'identifiant présenté : une clé de test a servi là où une clé de direct était attendue, ou l'inverse.
Réponse de l’APIThe key prefix does not match the credential. Check whether you meant a test or a live key.
N'importe quel point de terminaison peut le renvoyer.
insufficient_scope
403La clé est valide mais ne porte pas la portée qu'exige cette opération. Les portées sont figées à la création d'une clé : il en faut une qui porte la bonne.
Réponse de l’APIThis credential does not carry the scope required for this operation.
Quels points de terminaison le renvoient
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
organization_not_found_or_not_granted
404Aucune organisation ne correspond, ou bien elle existe mais cette clé n'y donne pas accès. Les deux cas donnent le même refus.
Réponse de l’APINo such organization.
Quels points de terminaison le renvoient
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
resource_not_found
404Rien ne correspond à l'identifiant demandé dans l'organisation visée.
Réponse de l’APINo such resource.
Quels points de terminaison le renvoient
- get
/categories/{category}/schema - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - get
/organizations/{organization}/imports/{id}
wildcard_not_supported
400Le joker d'organisation « - » est réservé pour un usage à venir et n'est pas encore pris en charge. Nommez explicitement l'organisation.
Réponse de l’APIThe "-" organization wildcard is reserved and not yet supported.
Quels points de terminaison le renvoient
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
validation_failed
422Le corps de la requête est bien formé mais ne satisfait pas le schéma. Les champs en cause sont nommés un à un dans details.
Réponse de l’APIThe request body failed validation.
Quels points de terminaison le renvoient
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
invalid_request
400La requête ne peut pas être interprétée telle qu'elle est formulée : forme, type ou combinaison de paramètres incompatible avec l'opération demandée.
Réponse de l’APIThe request could not be understood.
N'importe quel point de terminaison peut le renvoyer.
method_not_allowed
405Le point de terminaison existe mais ne répond pas à cette méthode HTTP. L'en-tête Allow du refus énumère celles auxquelles il répond.
Réponse de l’APIThis endpoint does not support that HTTP method. The Allow header lists the ones it does.
payload_too_large
413Le corps de la requête dépasse ce que ce point de terminaison accepte. details.limit_bytes indique le plafond appliqué.
Réponse de l’APIThe request body is larger than this endpoint accepts.
N'importe quel point de terminaison peut le renvoyer.
unsupported_media_type
415Le corps de la requête n'est pas arrivé en application/json.
Réponse de l’APIThe request body must be sent as application/json.
Quels points de terminaison le renvoient
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
idempotency_conflict
409Cette Idempotency-Key a déjà servi pour un corps de requête différent. Une clé d'idempotence est liée à la requête exacte qu'elle a enregistrée : une écriture différente exige une clé neuve.
Réponse de l’APIThis Idempotency-Key was already used with a different request body.
Quels points de terminaison le renvoient
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
precondition_failed
412La ressource a changé depuis la version que vous avez indiquée en If-Match. Relisez-la, réappliquez votre modification, puis renvoyez l'écriture avec le nouvel ETag.
Réponse de l’APIThe resource changed since the version you supplied.
resource_busy
409Une autre requête est en train de modifier cette ressource. Attendez le délai indiqué par l'en-tête Retry-After, puis réessayez.
Réponse de l’APIAnother request is modifying this resource. Wait for the Retry-After header, then retry.
Quels points de terminaison le renvoient
cursor_invalid
400Le curseur de pagination est illisible, expiré, ou il a été envoyé avec d'autres filtres que ceux sous lesquels il avait été émis. Reprenez la pagination à la première page.
Réponse de l’APIThe pagination cursor is invalid, expired, or was sent with different filters.
no_subscription
402L'organisation n'a aucun abonnement actif. Les opérations qui en dépendent restent fermées tant que ce n'est pas réglé.
Réponse de l’APIThis organization has no active subscription.
Quels points de terminaison le renvoient
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports
payment_overdue
402Un paiement est en retard sur cette organisation : la publication est suspendue jusqu'à sa régularisation.
Réponse de l’APIPublishing is disabled while payment is overdue.
Quels points de terminaison le renvoient
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports
gtin_required
422Le passeport ne porte pas de GTIN, et un GTIN est exigé avant toute publication. Renseignez-le, puis publiez.
Réponse de l’APIA GTIN is required before this passport can be published.
Quels points de terminaison le renvoient
wrong_status
409Le statut actuel du passeport n'autorise pas cette opération. Relisez le passeport pour connaître son statut avant de réessayer.
Réponse de l’APIThe passport is not in a status that allows this operation.
Quels points de terminaison le renvoient
not_trashed
409Seul un passeport mis à la corbeille peut être restauré, et celui-ci ne l'est pas.
Réponse de l’APIOnly a trashed passport can be restored.
Quels points de terminaison le renvoient
publish_limit_reached
402L'organisation a consommé tous les emplacements de publication que son offre autorise. Dépubliez un passeport ou changez d'offre.
Réponse de l’APIThis organization has used every publish slot its plan allows.
Quels points de terminaison le renvoient
unit_limit_reached
402Le nombre d'unités rattachées à ce passeport dépasse ce que l'offre autorise.
Réponse de l’APIThis passport carries more units than the plan allows.
Quels points de terminaison le renvoient
document_missing
422Un champ obligatoire n'était satisfait que par un document qui n'est plus rattaché au passeport. Rattachez-le de nouveau, ou renseignez le champ autrement.
Réponse de l’APIA required field is satisfied only by a document that is no longer attached.
Quels points de terminaison le renvoient
delegation_required
403Le dépôt exige une délégation active, vérifiée auprès du portail de l'État au moment même de l'appel. Aucune délégation valable n'a été trouvée.
Réponse de l’APIFiling requires an active delegation, verified against the portal at call time.
Quels points de terminaison le renvoient
attestation_required
403L'opération exige une attestation acceptée nommément par une personne de la marque. Aucune attestation de ce type n'est enregistrée.
Réponse de l’APIThis operation requires an attestation accepted by a named person at the brand.
Quels points de terminaison le renvoient
test_mode_refused
403Des identifiants de test ne peuvent pas exécuter cette opération : elle exige une clé de direct.
Réponse de l’APITest-mode credentials cannot perform this operation.
Quels points de terminaison le renvoient
rate_limited
429Trop de requêtes sur la fenêtre en cours. Attendez le délai indiqué par Retry-After plutôt que de réessayer aussitôt.
Réponse de l’APIToo many requests.
N'importe quel point de terminaison peut le renvoyer.
internal_error
500Quelque chose a échoué de notre côté. Votre requête était recevable : reprenez-la avec une nouvelle Idempotency-Key.
Réponse de l’APISomething went wrong on our side.
N'importe quel point de terminaison peut le renvoyer.
configuration_error
500Le service est mal configuré de notre côté. Votre requête n'est pas en cause, et la réessayer à l'identique ne changera rien tant que nous n'avons pas corrigé.
Réponse de l’APIThe service is misconfigured. This is not a problem with your request.
N'importe quel point de terminaison peut le renvoyer.
Avertissements
Un avertissement n'est pas un refus. Il accompagne une réponse 200, sur un appel qui a réussi, et signale un point qui mérite une action.
environmental_claim_detected
200Le passeport contient des formulations à caractère environnemental. La publication a réussi et le passeport est en ligne. À partir du 27 septembre 2026, la directive (UE) 2024/825 impose au professionnel qui met le produit sur le marché de disposer d'éléments justifiant de telles allégations.