Error Codes

This page outlines the canonical error codes that merchants integrating with Google using the Universal Commerce Protocol (UCP) should return in their API responses. Consistent error codes ensure clear communication and help Google handle different scenarios appropriately.

When a business error occurs, your API should return a response message that includes the appropriate code from the table. For some error codes, a specific JSON structure is recommended for the messages array in the response. These examples are provided in the Error Code Examples section below the table. In these examples, you should use the path field to provide more specific information about the location of the error within the request or response object.

Message Types: Error versus Warning

The type field in the message array indicates the severity of the issue. UCP defines two primary types:

• error: Indicates that the requested operation couldn't be completed. The platform or user will likely need to take action and try again. See message-error specification.
• warning: Indicates that the operation was not blocked, but there's something noteworthy that should be communicated to the user. This doesn't halt the process but provides important context. See message-warning specification.

Error Code Reference

Error Code	Recommended Type	Description
out_of_stock	Error	Item is not available. This typically results in ucp.status: “error”. See example below
item_unavailable	Error	Item couldn't be found. This typically results in ucp.status: “error” to these item related errors.
item_ineligible	Error	Item exists but cannot be purchased using UCP.
quantity_invalid_limit_exceeded	Error	The requested quantity exceeds the allowable limit. See example below.
quantity_invalid_minimum_not_met	Error	The requested quantity is below the minimum required.
totals_changed	Warning	The price or other totals have changed since the last step. Use the path field to indicate which total changed. See example below.
totals_invalid_minimum_not_met	Error	The order value does not meet the minimum requirement.
missing_buyer_info	Error	Required buyer information is missing. Use the path field to specify the missing field. See example below.
address_undeliverable	Error	This is a standard UCP error code. Use the path field to indicate the specific destination.
address_unverifiable	Error	The provided address couldn't be verified. Use the path field to indicate if it's the fulfillment or billing address. See example below.
missing_fulfillment_info	Error	Required fulfillment information is missing. Use the path field to specify the missing field.
eligibility_invalid	Error	User or order is not eligible for the action. This is a standard UCP error code. Use the path field for specifics.
discount_code_invalid	Warning	The discount code is invalid. Code not found or malformed.
discount_code_expired	Warning	The discount code has expired.
discount_code_already_applied	Warning	The discount code has already been applied.
discount_code_combination_disallowed	Warning	The discount code cannot be combined with other offers.
discount_code_user_not_logged_in	Warning	The user must be logged in to use the discount code.
discount_code_user_ineligible	Warning	The user is not eligible to use the discount code.
missing_billing_info	Error	Required billing information is missing. Use the path field to specify the missing billing address fields.
payment_declined	Error	The payment was declined by the issuer. Suitable for cases when the user needs to try a different payment method or contact their card issuer. See example below.
payment_failed	Error	The payment failed due to a general error. method.
payment_ineligible	Error	The selected payment method is not accepted. Suitable for cases when the user needs to try a different payment method.
rejected_for_fraud	Error	The order was rejected due to suspected fraud.

Error Code Examples

This section provides JSON examples for the messages array for specific error codes.

out_of_stock

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

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_unverifiable

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

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."
}