En esta guía, se explica cómo controlar los errores que muestra 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 muestra 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. De manera fundamental, 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:
- 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 control 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.,
Ejemplos de respuestas de error
El siguiente JSON 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 escribes lógica de control de errores, es importante saber en qué campos es seguro 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 de 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. Está destinado solo 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
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ó anteriormente, el valor dedetails.metadata.REASONes estable.
Prácticas recomendadas
Sigue estas prácticas recomendadas para asegurarte de que tu integración controle los errores correctamente.
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 dependas solo del 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 indicó en la sección de estabilidad, el campo message es para el consumo humano.
Si necesitas información dinámica (como qué campo no es válido), extráela del mapa metadata con claves estables como FIELD_LOCATION y VARIABLE_NAME.
Implementa una 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 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 por minuto 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: Siinternal_errorpersiste después de varios reintentos con retirada, consulta Cómo comunicarte con el equipo de asistencia de la API de Merchant support.
Cómo comunicarte con el equipo de asistencia de la API de Merchant
- La respuesta de error exacta recibida
- 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 errores