Codes d'erreur

Cette page récapitule les codes d'erreur canoniques que vous devez renvoyer dans vos réponses d'API lors de votre intégration à Google à l'aide du protocole Universal Commerce Protocol (UCP). L'utilisation de codes d'erreur cohérents garantit une communication claire et aide Google à traiter chaque scénario de manière appropriée.

Lorsqu'une erreur de logique métier se produit, votre API doit renvoyer un message de réponse incluant le code approprié figurant dans le tableau. Pour certains codes d'erreur, une structure JSON spécifique est recommandée pour le array messages de la réponse. Ces exemples sont fournis dans la section Exemples de codes d'erreur située sous le tableau. Dans ces exemples, vous devez utiliser le champ path pour fournir des informations plus spécifiques sur l'emplacement de l'erreur dans l'objet de requête ou de réponse.

Gestion des erreurs

La procédure à suivre pour signaler des erreurs dépend du type d'erreur :

Erreurs de protocole ou du serveur :
- Utilisez des status codes HTTP standards (par exemple, 4xx pour les erreurs client, 5xx pour les erreurs du serveur) pour les problèmes tels que les requêtes incorrectes, les échecs d'authentification ou l'indisponibilité du serveur.
- Pour en savoir plus, consultez la spécification UCP.
Erreurs/Avertissements de logique métier :
- Renvoyer un état HTTP 200 OK.
- Décrivez le problème dans le array messages du corps de la réponse JSON.
- Chaque objet du array messages doit inclure :
  - type : "error" ou "warning"
  - code : code standardisé issu de ce guide. N'utilisez pas de codes génériques ou non reconnus tels que "invalid".
  - content : description lisible par l'humain.
  - severity : obligatoire lorsque type est défini sur "error". Ce champ indique explicitement si l'erreur est définitive (unrecoverable) ou si vous pouvez inviter l'acheteur à corriger le problème (recoverable), ce qui évite d'avoir à se fier uniquement au code d'erreur lui-même.

Types de messages : erreur ou avertissement

Le champ type du array messages indique le niveau de gravité du problème. UCP définit deux types principaux :

error : indique que l'opération demandée n'a pas pu être effectuée. La plate-forme ou l'utilisateur devront probablement effectuer une action et réessayer. Consultez la spécification relative aux erreurs (message-error).
- Le caractère définitif d'une erreur est déterminé par le champ severity (unrecoverable ou recoverable), et non par l'erreur code.
warning : indique que l'opération n'a pas été bloquée, mais qu'un élément notable doit être communiqué à l'utilisateur. Cela n'arrête pas le processus, mais fournit un contexte important. Consultez la spécification relative aux avertissements (message-warning).

Informations de référence sur les codes d'erreur

Code d'erreur	Type recommandé	Description
`out_of_stock`	Erreur	L'article n'est pas disponible. Cela se traduit généralement par `ucp.status: “error”`. Utilisez le champ `path` pour indiquer l'index de l'article dans le cas de paiements multi-articles. Consultez l'exemple ci-dessous.
`item_unavailable`	Erreur	Article introuvable. Cela se traduit généralement par un `ucp.status: “error”` pour ces erreurs liées aux articles.
`item_ineligible`	Erreur	L'article existe, mais ne peut pas être acheté à l'aide de UCP.
`quantity_invalid_limit_exceeded`	Erreur	La quantité demandée dépasse la limite autorisée. Consultez l'exemple ci-dessous.
`quantity_invalid_minimum_not_met`	Erreur	La quantité demandée est inférieure au minimum requis.
`totals_changed`	Avertissement	Le prix ou d'autres montants totaux ont changé depuis la dernière étape. Utilisez le champ `path` pour indiquer quel montant total a changé. Consultez l'exemple ci-dessous.
`totals_invalid_minimum_not_met`	Erreur	La valeur de la commande n'atteint pas le montant minimal requis.
`missing_buyer_info`	Erreur	Il manque des informations obligatoires sur l'acheteur. Utilisez le champ `path` pour indiquer le champ manquant. Consultez l'exemple ci-dessous.
`address_undeliverable`	Erreur	Il s'agit d'un code d'erreur UCP standard. Utilisez le champ `path` pour indiquer la destination spécifique ou l'article soumis à restriction. Consultez l'exemple ci-dessous.
`address_unverifiable`	Erreur	Impossible de valider l'adresse fournie. Utilisez le champ `path` pour indiquer s'il s'agit de l'adresse de traitement ou de livraison. Consultez l'exemple ci-dessous.
`missing_fulfillment_info`	Erreur	Il manque des informations obligatoires sur le traitement. Utilisez le champ `path` pour indiquer le champ manquant.
`eligibility_invalid`	Erreur	L'utilisateur ou la commande ne sont pas éligibles pour l'action. Il s'agit d'un code d'erreur UCP standard. Utilisez le champ `path` pour apporter des précisions.
`discount_code_invalid`	Avertissement	Le code de réduction n'est pas valide. Le code est introuvable ou son format est incorrect.
`discount_code_expired`	Avertissement	Le code de réduction a expiré.
`discount_code_already_applied`	Avertissement	Le code de réduction a déjà été appliqué.
`discount_code_combination_disallowed`	Avertissement	Le code de réduction n'est pas cumulable avec d'autres offres.
`discount_code_user_not_logged_in`	Avertissement	L'utilisateur doit être connecté pour utiliser le code de réduction.
`discount_code_user_ineligible`	Avertissement	L'utilisateur n'est pas éligible à ce code de réduction.
`missing_billing_info`	Erreur	Il manque des informations obligatoires sur la facturation. Utilisez le champ `path` pour indiquer les champs manquants dans l'adresse de facturation. Consultez l'exemple ci-dessous.
`identity_required`	Erreur	L'identité de l'utilisateur est requise pour l'opération demandée, mais elle est absente, non valide, expirée ou impossible à vérifier. Pour REST, utilisez le status code 401. Consultez l'exemple ci-dessous.
`insufficient_scope`	Erreur	Le jeton d'identité de l'utilisateur est valide, mais il ne dispose pas du ou des niveaux d'accès requis pour l'opération. Pour REST, utilisez le status code 403. Consultez l'exemple ci-dessous.
`payment_declined`	Erreur	Le paiement a été refusé par l'émetteur de la carte ou la banque. Cela peut être dû à des fonds insuffisants, une suspicion de fraude ou un problème avec la carte. Consultez l'exemple ci-dessous.
`payment_failed`	Erreur	Le paiement a échoué en raison d'un problème technique lors du traitement (tel qu'une erreur réseau, un délai d'expiration de la passerelle ou un problème d'intégration), ce qui a empêché la banque de prendre une décision.
`payment_ineligible`	Erreur	Le mode de paiement sélectionné n'est pas accepté. S'utilise lorsque l'utilisateur doit essayer un autre mode de paiement.
`rejected_for_fraud`	Erreur	La commande a été rejetée pour suspicion de fraude.

Exemples de codes d'erreur

Cette section présente des exemples JSON pour le array messages associés à des codes d'erreur spécifiques.

`out_of_stock`

Paiement pour un seul article :

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

Paiement pour plusieurs articles :

Utilisez le champ path pour indiquer l'index de l'article spécifique qui est non disponible.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

`quantity_invalid_limit_exceeded`

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

`totals_changed`

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

`missing_buyer_info`

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

`address_undeliverable`

Restriction au niveau de la commande (par exemple, code postal non disponible) :

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

Restriction au niveau de l'article :

Utilisez le champ path pour indiquer un article spécifique qui ne peut pas être livré à la destination choisie (par exemple, en raison d'une interdiction spécifique à un État).

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

`address_unverifiable`

Adresse de facturation :

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

Adresse de traitement :

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

`missing_billing_info`

Utilisez le champ path pour spécifier les champs manquants dans l'adresse de facturation.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

`identity_required`

Dans l'API REST, cette erreur doit être renvoyée avec le status code HTTP 401.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

`insufficient_scope`

Dans l'API REST, cette erreur doit être renvoyée avec le status code HTTP 403.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

`payment_declined`

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

Cycle de vie d'une commande (après l'achat)

Codes d'erreur Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Gestion des erreurs

Types de messages : erreur ou avertissement

Informations de référence sur les codes d'erreur

Exemples de codes d'erreur

out_of_stock

quantity_invalid_limit_exceeded

totals_changed

missing_buyer_info

address_undeliverable

address_unverifiable

missing_billing_info

identity_required

insufficient_scope

payment_declined