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.

Réponse
{
  "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

401

Aucune 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

401

La 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

401

La 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

401

La 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

400

Le 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.

invalid_request

400

La 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

405

Le 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

413

Le 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.

idempotency_conflict

409

Cette 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

precondition_failed

412

La 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.

Quels points de terminaison le renvoient

resource_busy

409

Une 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

400

Le 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.

Quels points de terminaison le renvoient

gtin_required

422

Le 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

409

Le 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

409

Seul 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

402

L'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

402

Le 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

422

Un 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

403

Le 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

403

L'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

403

Des 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

portal_unavailable

502

Le portail de l'État pour l'affichage environnemental français n'a pas pu être joint. Rien n'a donc été déposé, et l'appel peut être repris tel quel.

Réponse de l’APIThe French affichage portal could not be reached, so nothing was filed.

Quels points de terminaison le renvoient

storage_unavailable

503

Nous n'avons pas pu confirmer que les fichiers téléversés se trouvent bien dans le stockage ; rien n'a donc été publié. Votre requête n'a rien d'incorrect — réessayez après le délai indiqué par l'en-tête Retry-After.

Réponse de l’APIWe 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.

Quels points de terminaison le renvoient

entitlement_unavailable

503

Nous n'avons pas pu confirmer les droits de cette organisation ; rien n'a donc été déposé. Ce n'est pas un constat sur l'abonnement — réessayez après le délai indiqué par l'en-tête Retry-After.

Réponse de l’APIWe 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.

Quels points de terminaison le renvoient

rate_limited

429

Trop 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

500

Quelque 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

500

Le 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

200

Le 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.

Erreurs — API PassportCraft | PassportCraft