En esta guía, se explica cómo controlar los errores que devuelve la API de Merchant. Comprender la estructura y la estabilidad de la respuesta 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áquinas 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 manera 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 estables y estructurados sobre el error:
- domain: Es la agrupación lógica del error, por lo general,
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 el 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 para 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: Son otras claves que proporcionan contexto, como el nombre
del campo no válido (
FIELD_LOCATION) o el valor que causó el error (FIELD_VALUE).
- REASON: Es un identificador específico y estable para el error exacto (p.ej.,
Respuestas de error de muestra
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 la lógica de manejo 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 confiar en este campo para la lógica del flujo de control de tu aplicación.- Claves
details.metadata: Las claves dentro del mapa de metadatos (p.ej.,FIELD_LOCATION,ACCOUNT_IDS) son estables. code: El código de estado HTTP de alto nivel (p.ej.,400,401,503) es estable.
- Claves
Campos inestables:
message: El mensaje de error legible por humanos no es estable. Solo está destinado a la depuración de desarrolladores. No escribas código que analice o dependa del contenido de texto del campomessage, 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 claveHELP_CENTER_LINK, la URL específica a la que apunta podría actualizarse a una página de documentación más reciente sin notificación previa. Sin embargo, como se mencionó antes, el valor dedetails.metadata.REASONes 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
Usa siempre 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 analices el mensaje de error
Como se indica en la sección de estabilidad, el campo message es para 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, VARIABLE_NAME.
Implementa la retirada exponencial
En el caso de los errores que indican una falta de disponibilidad temporal o un límite de frecuencia, implementa una estrategia de retirada exponencial. Esto significa esperar un período breve antes de volver a intentarlo y aumentar el tiempo de espera con cada falla posterior.
quota/request_rate_too_high: Este error indica que superaste 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.
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 informar un error específico, proporciona la siguiente información en tu solicitud:
- La respuesta de error exacta que se recibió
- El nombre del método de la API
- La carga útil de la solicitud
- Marcas de tiempo o el período durante el cual se llamó al método y se recibieron los errores