Códigos de error: documentación de CheckoutOS

Esta referencia cubre los códigos que puedes encontrar al usar CheckoutOS. Cada error incluye su significado y pasos recomendados para resolverlo.

Encontrar códigos de error

Los códigos aparecen en notificaciones del panel, consola del navegador y respuestas de webhook. Busca el formato COS-XXXX.

Errores de instalación (COS-1XXX)

COS-1001: Falló la conexión con Shopify

Causa: No se pudo conectar con tu tienda de Shopify.

Soluciones:

Verifica que la URL de la tienda sea correcta
Comprueba que la tienda esté activa, no pausada ni suspendida
Reinstala CheckoutOS desde Shopify App Store
Asegúrate de tener permisos de administrador o propietario

COS-1002: Permiso denegado

Causa: CheckoutOS no tiene los permisos necesarios.

Soluciones:

Reinstala la app para volver a autorizar permisos
Verifica que hayas iniciado sesión como propietario o administrador
Revisa los permisos en Shopify Admin → Apps → CheckoutOS

COS-1003: Checkout Extensibility no disponible

Causa: Tu plan no admite extensiones del checkout.

Soluciones:

Pasa a Shopify Plus para extensibilidad completa
Solicita acceso beta a Checkout Extensibility si no tienes Plus
Usa solo funciones posteriores a la compra, disponibles en todos los planes

Errores de campaña (COS-2XXX)

COS-2001: Configuración de campaña no válida

Causa: Faltan ajustes o son incorrectos.

Soluciones:

Revisa todos los campos obligatorios
Selecciona al menos un producto de venta adicional
Comprueba que los descuentos estén en rangos válidos

Estructura válida de campaña

{
  "name": "Summer Upsell",
  "active": true,
  "products": ["gid://shopify/Product/123"],
  "discount": {
    "type": "percentage",
    "value": 20
  },
  "targeting": {
    "minCartValue": 50
  }
}

COS-2002: Producto no encontrado

Causa: Un producto de la campaña ya no existe o no está disponible.

Soluciones:

Comprueba si se eliminó del catálogo de Shopify
Verifica que esté publicado y activo
Actualiza la campaña con identificadores válidos

COS-2003: Conflicto de segmentación

Causa: Las reglas de segmentación se contradicen.

Soluciones:

Revisa la lógica AND/OR de las reglas
Comprueba que mínimos y máximos no se superpongan incorrectamente
Busca condiciones imposibles, como carrito > US$100 Y carrito < US$50

Errores de checkout (COS-3XXX)

COS-3001: No se pudo aplicar el descuento

Causa: No se pudo descontar el producto de venta adicional.

Soluciones:

Busca códigos de Shopify en conflicto
Verifica las opciones de combinación de descuentos
Comprueba que el producto no esté excluido

COS-3002: Error al procesar el pago

Causa: No se pudo cobrar el producto de venta adicional.

Soluciones:

Suele ser un problema de la pasarela de Shopify
Revisa su estado en Shopify Admin → Settings → Payments
El cliente puede necesitar otro método de pago

Errores de pago

CheckoutOS nunca almacena información de pago. Los errores se procesan mediante la infraestructura segura de Shopify. Consulta allí los registros detallados.

COS-3003: Inventario no disponible

Causa: El producto de venta adicional está agotado.

Soluciones:

Activa alternativas de seguimiento de inventario en la campaña
Configura productos de respaldo para artículos agotados
Si corresponde, configura "Continue selling when out of stock" en Shopify

Errores de API (COS-4XXX)

COS-4001: Clave de API no válida

Causa: La solicitud usó una clave no válida o caducada.

Soluciones:

Regenera la clave en Dashboard → Settings → API
Busca errores de escritura o espacios en la clave
Comprueba que tenga los permisos necesarios

COS-4002: Límite de solicitudes superado

Causa: Demasiadas solicitudes en poco tiempo.

Soluciones:

Limita la frecuencia de solicitudes en tu aplicación
Usa webhooks en lugar de consultas periódicas
Contacta con soporte si necesitas límites mayores

Cabeceras de límites

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642345678
Retry-After: 60

COS-4003: Firma de webhook no válida

Causa: Falló la verificación de firma.

Soluciones:

Verifica que el secreto coincida con Dashboard → Settings → API
Usa el cuerpo original de la solicitud para verificar la firma
Comprueba que el reloj del servidor esté sincronizado

Errores de extensión (COS-5XXX)

COS-5001: La extensión no cargó

Causa: La extensión no pudo cargar en el navegador.

Soluciones:

Busca errores JavaScript en la consola
Desactiva temporalmente bloqueadores de anuncios o extensiones de privacidad
Borra la caché y reintenta
Prueba otro navegador

COS-5002: Error al mostrar la extensión

Causa: Cargó, pero no pudo mostrarse correctamente.

Soluciones:

Busca conflictos de CSS personalizado
Verifica que las URL de imágenes sean válidas y accesibles
Busca ajustes no válidos en la extensión

¿Necesitas más ayuda?

Preguntas frecuentes

Respuestas a preguntas frecuentes

Más información

Contactar al soporte

Recibe ayuda personalizada de nuestro equipo

Más información