Cómo controlar las respuestas de error

En esta guía, se explica cómo controlar los errores que devuelve la API de Merchant. Comprender la estructura y la estabilidad de las respuestas de error es fundamental para crear integraciones sólidas que puedan recuperarse automáticamente de las fallas o proporcionar comentarios significativos a los usuarios.

Descripción general

Cuando falla una solicitud a la API de Merchant, la API devuelve un código de estado HTTP estándar (4xx o 5xx) y un cuerpo de respuesta JSON que contiene detalles sobre el error. La API de Merchant sigue el estándar AIP-193 para los detalles de los errores, lo que proporciona información legible por máquina que permite que tu aplicación controle situaciones de error específicas de forma programática.

Estructura de la respuesta de error

La respuesta de error es un objeto JSON que contiene campos estándar como code, message y status. Fundamentalmente, también incluye un array details. Para controlar los errores de forma programática, debes buscar un objeto dentro de details en el que @type sea type.googleapis.com/google.rpc.ErrorInfo.

Este objeto ErrorInfo proporciona datos estructurados y estables sobre el error:

  • dominio: Es la agrupación lógica del error, que suele ser merchantapi.googleapis.com.
  • metadata: Es un mapa de valores dinámicos relacionados con el error. Incluye lo siguiente:
    • REASON: Es un identificador específico y estable para el error exacto (p.ej., INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Este campo siempre está presente. Usa este campo para un manejo de errores detallado en la lógica de tu aplicación.
    • HELP_CENTER_LINK: Proporciona contexto e instrucciones adicionales para solucionar el problema. Este campo no está presente en todos los errores, pero planeamos expandir su cobertura con el tiempo para los errores en los que se podría necesitar más contexto.
    • Otros campos dinámicos: Otras claves que proporcionan contexto, como el nombre del campo no válido (FIELD_LOCATION) o el valor que causó el error (FIELD_VALUE).

Ejemplos de respuestas de error

En el siguiente JSON, se muestra la estructura de un error de la API de Merchant en el que el nombre de un recurso tenía un formato incorrecto.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

Este es un ejemplo de un error de autenticación:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

Estabilidad de los campos de error

Cuando escribas lógica de control de errores, es importante que sepas en qué campos puedes confiar y cuáles podrían cambiar.

  • Campos estables:

  • details.metadata.REASON: Es el identificador de error específico. Debes basarte en este campo para la lógica de flujo de control de tu aplicación.

    • Claves de details.metadata: Son las claves dentro del mapa de metadatos (p.ej., FIELD_LOCATION, ACCOUNT_IDS) son estables.
    • code: Es el código de estado HTTP de alto nivel (p.ej., 400, 401, 503) es estable.

  • Campos inestables:

    • message: El mensaje de error legible para el ser humano no es estable. Solo se debe usar para la depuración de desarrolladores. No escribas código que analice o dependa del contenido de texto del campo message, ya que puede cambiar sin previo aviso para mejorar la claridad o agregar contexto.
    • Valores de details.metadata: Si bien las claves son estables, los valores de las claves informativas pueden cambiar. Por ejemplo, si se proporciona una clave de HELP_CENTER_LINK, es posible que la URL específica a la que apunta se actualice a una página de documentación más reciente sin previo aviso. Sin embargo, como se mencionó anteriormente, el valor de details.metadata.REASON es estable.

Prácticas recomendadas

Sigue estas prácticas recomendadas para asegurarte de que tu integración controle los errores de forma correcta.

Usa details.metadata.REASON para la lógica

Siempre usa el REASON específico dentro del mapa metadata para determinar la causa de un error. No confíes solo en el código de estado HTTP, ya que varios errores pueden compartir el mismo código de estado.

No se analiza el mensaje de error

Como se indica en la sección de estabilidad, el campo message es para el consumo humano. Si necesitas información dinámica (como qué campo no era válido), extráela del mapa metadata con claves estables, como FIELD_LOCATION y VARIABLE_NAME.

Implementa la retirada exponencial

Para los errores que indican una falta de disponibilidad temporal o una limitación de frecuencia, implementa una estrategia de retirada exponencial. Esto significa esperar un período breve antes de reintentar y aumentar el tiempo de espera con cada falla posterior.

  • quota/request_rate_too_high: Este error indica que excediste tu cuota de minutos para un grupo de cuotas específico. Disminuye el porcentaje de solicitudes.
  • internal_error: Por lo general, son transitorios. Vuelve a intentarlo con una retirada exponencial. Nota: Si internal_error persiste después de varios reintentos con espera exponencial, consulta Cómo comunicarte con el equipo de asistencia al cliente de la API de Merchant.

Cómo comunicarse con el equipo de asistencia de la API de Merchant

Si necesitas comunicarte con el equipo de asistencia de la API de Merchant para consultar sobre un error específico, proporciona la siguiente información en tu solicitud:

  1. La respuesta de error exacta que se recibió
  2. El nombre del método de la API
  3. La carga útil de la solicitud
  4. Marcas de tiempo o el intervalo durante el que se llamó al método y se recibieron errores