Códigos de erro: documentação do CheckoutOS

Esta referência reúne os códigos de erro que você pode encontrar ao usar o CheckoutOS. Cada erro inclui seu significado e as etapas recomendadas para resolvê-lo.

Onde encontrar os códigos de erro

Os códigos aparecem nas notificações do painel do CheckoutOS, no console do navegador e nas respostas de webhooks. Procure códigos no formato COS-XXXX.

Erros de instalação (COS-1XXX)

COS-1001: falha na conexão com Shopify

Causa: Não foi possível estabelecer conexão com sua loja Shopify.

Soluções:

Verifique se a URL da loja Shopify está correta
Confira se a loja Shopify está ativa, sem pausa nem suspensão
Reinstale o app CheckoutOS pela Shopify App Store
Confirme que você tem permissão de administrador ou proprietário da loja

COS-1002: permissão negada

Causa: O CheckoutOS não tem as permissões necessárias.

Soluções:

Reinstale o app para autorizar as permissões novamente
Confirme que você está conectado como proprietário ou administrador
Confira o status das permissões em Shopify Admin → Apps → CheckoutOS

COS-1003: Checkout Extensibility indisponível

Causa: Seu plano Shopify não oferece suporte a extensões de checkout.

Soluções:

Mude para Shopify Plus para obter acesso completo à extensibilidade do checkout
Solicite acesso ao beta de Checkout Extensibility para lojas sem Plus
Use apenas os recursos pós-compra, disponíveis em todos os planos

Erros de campanha (COS-2XXX)

COS-2001: configuração de campanha inválida

Causa: A campanha tem configurações ausentes ou inválidas.

Soluções:

Revise todos os campos obrigatórios da campanha
Confirme que pelo menos um produto foi selecionado para venda adicional
Verifique se os valores de desconto estão dentro dos limites válidos

Estrutura válida de campanha

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

COS-2002: produto não encontrado

Causa: Um produto da campanha não existe mais ou está indisponível.

Soluções:

Confira se o produto foi excluído do catálogo Shopify
Verifique se o produto está publicado e ativo
Atualize a campanha com IDs de produtos válidos

COS-2003: conflito nas regras de segmentação

Causa: As regras de segmentação da campanha se contradizem.

Soluções:

Revise a lógica AND/OR das regras de segmentação
Confirme que os valores mínimos e máximos não se sobrepõem incorretamente
Procure condições impossíveis, como carrinho > US$100 E carrinho < US$50

Erros de checkout (COS-3XXX)

COS-3001: falha ao aplicar desconto

Causa: Não foi possível aplicar o desconto ao produto da oferta adicional.

Soluções:

Procure códigos de desconto da Shopify em conflito
Verifique as configurações de combinação de descontos na Shopify
Confirme que o produto não está excluído dos descontos

COS-3002: erro no processamento de pagamento

Causa: Não foi possível cobrar o cliente pelo produto da oferta adicional.

Soluções:

Normalmente, esse é um problema no gateway de pagamento da Shopify
Confira o status do gateway em Shopify Admin → Settings → Payments
O cliente pode precisar tentar novamente com outra forma de pagamento

Erros de pagamento

O CheckoutOS nunca armazena informações de pagamento. Os erros de pagamento são processados pela infraestrutura segura da Shopify. Consulte os logs detalhados de pagamento na Shopify.

COS-3003: estoque indisponível

Causa: O produto da oferta adicional está sem estoque.

Soluções:

Ative alternativas de rastreamento de estoque nas configurações da campanha
Configure produtos de reserva para situações de falta de estoque
Configure "Continue selling when out of stock" na Shopify, se apropriado

Erros da API (COS-4XXX)

COS-4001: chave de API inválida

Causa: A requisição à API usou uma chave inválida ou expirada.

Soluções:

Gere novamente a chave em Dashboard → Settings → API
Verifique erros de digitação ou espaços em branco na chave
Confirme que a chave tem as permissões necessárias

COS-4002: limite de requisições excedido

Causa: Muitas requisições à API em um período curto.

Soluções:

Implemente limitação de requisições na aplicação
Use eventos de webhook em vez de consultas repetidas
Entre em contato com o suporte se precisar de limites maiores

Cabeçalhos de limite de requisições

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

COS-4003: assinatura de webhook inválida

Causa: A verificação da assinatura do webhook falhou.

Soluções:

Confirme que o segredo do webhook corresponde ao de Dashboard → Settings → API
Use o corpo bruto da requisição para verificar a assinatura
Confira se o relógio do servidor está sincronizado

Erros de extensão (COS-5XXX)

COS-5001: falha ao carregar a extensão

Causa: A extensão de checkout não carregou no navegador.

Soluções:

Verifique erros de JavaScript no console do navegador
Desative temporariamente bloqueadores de anúncios ou extensões de privacidade
Limpe o cache do navegador e tente novamente
Teste em outro navegador

COS-5002: erro de renderização da extensão

Causa: A extensão carregou, mas não foi renderizada corretamente.

Soluções:

Verifique conflitos de CSS personalizado
Confirme que as URLs das imagens são válidas e acessíveis
Revise a configuração da extensão em busca de valores inválidos

Precisa de mais ajuda?

Perguntas frequentes

Respostas às perguntas frequentes

Saiba mais

Fale com o suporte

Receba ajuda personalizada da nossa equipe

Saiba mais