Errores
Errores comunes de Listano Control MCP y orientación para su recuperación.
Las herramientas de Listano Control MCP pueden devolver errores de autenticación, permisos, validación, comprobaciones de preparación para publicación o fallos de fetch del backend.
El patrón de recuperación más seguro es:
- inspeccionar el error
- llamar a
whoamisi los permisos no están claros - llamar a
get-offeringsi el estado actual del borrador no está claro - corregir solo los datos inválidos o faltantes específicos
- llamar a
check-offering-publish-readinessde nuevo antes de publicar
Errores de permisos
Un error de permisos significa que la integración autenticada no tiene el scope requerido.
| Operación | Scope requerido |
|---|---|
| listar/leer/comprobar | catalog:read |
| crear/actualizar/traducir/descartar | catalog:write |
| publicar/retirar | catalog:publish |
Recuperación:
- llama a
whoami - confirma los scopes otorgados
- solicita que se otorgue el scope faltante
Errores de no encontrado
Una oferta puede no encontrarse cuando:
- el
offeringIdes incorrecto - la oferta pertenece a otra empresa
- la integración está autenticada para una empresa diferente
Recuperación:
- llama a
list-offeringscon un título, SKU u otro identificador conocido - confirma la oferta seleccionada antes de modificarla
Errores de validación
Los errores de validación suelen significar que la forma del input o el valor de un campo es inválido.
Causas frecuentes:
| Causa | Solución |
|---|---|
category_id sin category_label | Proporciona ambos campos. |
| Código de idioma inválido | Usa get-supported-languages. |
| Idioma principal incluido en las traducciones | Elimina el idioma principal del payload de traducción. |
| Código de unidad inválido | Usa un código de unidad válido de 3 caracteres. |
Atributo con unit pero valor no numérico | Usa un valor numérico. |
Atributo con valueLabel pero valor no string | Usa un valor string. |
Intento de cambiar kind o language | Descarta el borrador y crea una nueva oferta. |
Errores de preparación para publicación
check-offering-publish-readiness devuelve:
{
offeringId: string
publishable: boolean
errors: unknown[]
}Cuando publishable es false, no llames a publish-offering.
Problemas de preparación frecuentes:
- título, descripción o unidad de medida faltantes en el idioma principal
- traducciones faltantes para los idiomas no principales admitidos
- etiquetas de categoría traducidas faltantes
- traducciones de atributos faltantes
- combinación inválida de valor/unidad del atributo
- descripciones de atributos traducidas o etiquetas de valor faltantes
Recuperación:
- corrige los errores devueltos
- llama a
check-offering-publish-readinessde nuevo - publica solo cuando
publishableseatrue
Errores de ciclo de vida del borrador
Si kind o language es incorrecto, no intentes corregirlo mediante un patch.
Estos campos son inmutables. La recuperación correcta es descartar el borrador con discard-offering-draft y crear una nueva oferta.
Si una oferta ya tiene una versión actual publicada, descartar el borrador no elimina la versión activa.
Errores de publicación
publish-offering puede fallar si el borrador está incompleto o es inválido.
Recuperación:
- llama a
check-offering-publish-readiness - corrige los errores devueltos
- intenta publicar solo después de que la preparación pase
Fallos de fetch del backend
Una herramienta puede devolver un fallo de fetch cuando la solicitud al backend falla antes de obtener una respuesta válida.
Recuperación:
- reintenta la misma operación de solo lectura si es adecuado
- evita repetir llamadas de modificación a menos que hayas comprobado el estado actual con
get-offering - informa el mensaje de error si el fallo persiste