Códigos de error

En esta página, se describen los códigos de error canónicos que debes devolver en las respuestas de la API cuando realices la integración con Google a través del Universal Commerce Protocol (UCP). Los códigos de error coherentes garantizan una comunicación clara y ayudan a Google a controlar diferentes situaciones de manera adecuada.

Cuando se produce un error comercial, tu API debe devolver un mensaje de respuesta que incluya el code adecuado de la tabla. Para algunos códigos de error, se recomienda una estructura JSON específica para el array messages en la respuesta. Estos ejemplos se proporcionan en la sección Ejemplos de códigos de error que se encuentra debajo de la tabla. En estos ejemplos, debes usar el campo path para proporcionar información más específica sobre la ubicación del error dentro del objeto de solicitud o respuesta.

Manejo de errores

La forma de informar errores depende del tipo de error:

  • Errores de protocolo o servidor:

    • Usa códigos de estado HTTP estándar (p.ej., 4xx para errores del cliente y 5xx para errores del servidor) para problemas como solicitudes con formato incorrecto, fallas de autenticación o falta de disponibilidad del servidor.
    • Consulta la Especificación de UCP para obtener más detalles.

  • Errores o advertencias de lógica empresarial:

    • Devuelve un estado HTTP 200 OK. Esto incluye los rechazos de pagos y los rechazos por fraude, incluso si tu puerta de enlace de pagos descendente muestra un error 4xx o 5xx.
    • Describe el problema dentro del array messages en el cuerpo de la respuesta JSON.
    • Cada objeto del array messages debe incluir lo siguiente:
      • type: "error" o "warning"
      • code: Es un código estandarizado de esta guía. No uses códigos genéricos o no reconocidos, como "invalid".
      • content: Es una descripción legible.
      • severity: Es obligatorio cuando type es "error". Este campo indica explícitamente si el error es terminal (unrecoverable) o te permite solicitarle al comprador que corrija el problema (recoverable), en lugar de depender del código de error en sí.

Tipos de mensajes: Error versus advertencia

El campo type en el array de mensajes indica la gravedad del problema. La UCP define dos tipos principales:

  • error: Indica que no se pudo completar la operación solicitada. Es probable que la plataforma o el usuario deban tomar medidas y volver a intentarlo. Consulta la especificación de message-error.
    • La naturaleza terminal de un error se determina por el campo severity (unrecoverable o recoverable), no por el error code.
  • warning: Indica que la operación no se bloqueó, pero hay algo notable que se debe comunicar al usuario. Esto no detiene el proceso, pero proporciona un contexto importante. Consulta la especificación de message-warning.

Referencia de código de error

Código de error Tipo recomendado Descripción
out_of_stock Error El artículo no está disponible. Por lo general, esto da como resultado ucp.status: “error”. Usa el campo path para indicar el índice del elemento en las confirmaciones de compra con varios elementos. Consulta el ejemplo a continuación.
item_unavailable Error No se pudo encontrar el elemento. Por lo general, esto genera ucp.status: “error” para estos errores relacionados con el elemento.
item_ineligible Error El elemento existe, pero no se puede comprar con la UCP.
quantity_invalid_limit_exceeded Error La cantidad solicitada supera el límite permitido. Consulta el ejemplo a continuación.
quantity_invalid_minimum_not_met Error La cantidad solicitada es inferior a la cantidad mínima requerida.
totals_changed Advertencia El precio o los demás totales cambiaron desde el último paso. Usa el campo path para indicar qué total cambió. Consulta el ejemplo a continuación.
totals_invalid_minimum_not_met Error El valor del pedido no cumple con el requisito mínimo.
missing_buyer_info Error Falta la información obligatoria del comprador. Usa el campo path para especificar el campo faltante. Consulta el ejemplo a continuación.
address_undeliverable Error Este es un código de error estándar de UCP. Usa el campo path para indicar el destino específico o el artículo restringido. Consulta el ejemplo a continuación.
address_unverifiable Error No se pudo verificar la dirección proporcionada. Usa el campo path para indicar si se trata de la dirección de facturación o de envío. Consulta el ejemplo a continuación.
missing_fulfillment_info Error Falta información de cumplimiento obligatoria. Usa el campo path para especificar el campo faltante.
eligibility_invalid Error El usuario o el pedido no son aptos para la acción. Este es un código de error estándar de UCP. Usa el campo path para obtener detalles.
discount_code_invalid Advertencia El código de descuento no es válido. No se encontró el código o tiene un formato incorrecto.
discount_code_expired Advertencia El código de descuento venció.
discount_code_already_applied Advertencia Ya se aplicó el código de descuento.
discount_code_combination_disallowed Advertencia El código de descuento no se puede combinar con otras ofertas.
discount_code_user_not_logged_in Advertencia El usuario debe estar conectado para usar el código de descuento.
discount_code_user_ineligible Advertencia El usuario no es apto para usar el código de descuento.
missing_billing_info Error Falta la información de facturación obligatoria. Usa el campo path para especificar los campos de dirección de facturación que faltan. Consulta el ejemplo a continuación.
identity_required Error Se requiere la identidad del usuario para la operación solicitada, pero no se proporcionó, no es válida, venció o no se puede verificar. En el caso de REST, usa el código de estado 401. Consulta el ejemplo a continuación.
insufficient_scope Error El token de identidad del usuario es válido, pero no tiene los permisos que requiere la operación. En el caso de REST, usa el código de estado 403. Consulta el ejemplo a continuación.
payment_declined Error La entidad emisora de la tarjeta o el banco rechazaron el pago. Entre los motivos, se pueden incluir fondos insuficientes, sospecha de fraude o problemas con la tarjeta. Consulta el ejemplo a continuación.
payment_failed Error El pago falló debido a un problema técnico durante el procesamiento, como un error de red, un tiempo de espera agotado de la puerta de enlace o un problema de integración, que impidió que el banco tomara una decisión.
payment_ineligible Error No se acepta la forma de pago seleccionada. Es adecuado para los casos en los que el usuario necesita probar otra forma de pago.
rejected_for_fraud Error Se rechazó el pedido debido a sospechas de fraude. Consulta el ejemplo a continuación.

Ejemplos de códigos de error

En esta sección, se proporcionan ejemplos de JSON para el array messages para códigos de error específicos.

out_of_stock

Confirmación de compra de un solo artículo:

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

Cobro de varios artículos:

Usa el campo path para indicar el índice del elemento específico que está agotado.

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

Restricción a nivel del pedido (p.ej., no admitido el código postal):

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

Restricción a nivel del artículo:

Usa el campo path para indicar un artículo específico que no se puede entregar en el destino elegido (p.ej., prohibiciones específicas del estado).

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

Dirección de facturación:

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

Dirección de entrega:

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

Usa el campo path para especificar los campos faltantes en la dirección de facturación.

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

identity_required

En la API de REST, este error se debe devolver con el código de estado HTTP 401.

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

insufficient_scope

En la API de REST, este error se debe mostrar con el código de estado 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"
}

Errores de pago

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

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}