Pular para o conteúdo principal
Técnico

Erro de validação de carrinho ou checkout do Shopify não aparece? 9 causas e correções

Jahangir Alam21 de novembro de 2026Fatos verificados em 21 de novembro de 202610 min read

Quando uma regra de validação do Shopify não mostra mensagem, geralmente acontece uma de quatro coisas: a validação está desativada, a Function falhou e o checkout seguiu sem ela, a regra só roda no checkout, ou o tema recebeu o erro e não o mostrou. Teste a página do produto, o carrinho e o checkout, um de cada vez, para achar qual é.

Este guia trata da validação de checkout criada com Shopify Functions, que é como apps de limite de pedido, pedido mínimo e horário de funcionamento (o OrderRules inclusive) bloqueiam pedidos. Se você está começando, veja primeiro como funciona a validação de checkout do Shopify.

Onde o Shopify mostra erros de validação

O lugar onde a mensagem aparece depende de onde o cliente está.

Onde o cliente estáO que aconteceQuem mostra a mensagem
CheckoutO erro bloqueia a etapa. Um erro no carrinho inteiro aparece na página atual do checkout; um erro em um campo aparece junto dele.Shopify
Página do produto ou carrinho (adicionar ou alterar itens)A requisição do carrinho falha e retorna o erro.Seu tema, se ele ler o erro
Vitrine headlessOs erros aparecem no carrinho da Storefront API.Seu front-end
Checkout expresso (Shop Pay, Apple Pay, Google Pay, PayPal, Buy it now)A validação roda como no checkout.Shopify

A linha do meio é onde as mensagens somem. O Shopify devolve o erro; se o comprador o vê, depende do JavaScript do tema.

As 9 causas, por sintoma

SintomaCausa provávelCorreção
Nenhuma regra dispara, em lugar nenhum1. Validação não ativaAtive em Regras de checkout
Funciona em carrinhos pequenos, não nos grandes2. A Function travou ou estourou as instruçõesAvise o desenvolvedor do app com o horário e o tamanho do carrinho
Nada na página do carrinho, bloqueia no checkout3. A regra roda só no checkoutEsperado; avise os clientes com antecedência
"Sold out" ou erro genérico no lugar da sua mensagem4. O tema esconde ou substitui o erro do carrinhoTeste no Dawn; corrija o tratamento de erros do tema
Funciona pelo carrinho, não pelo Buy it now5. O checkout expresso ignorou os atributos do carrinhoSalve a escolha por item do pedido ou exija no checkout
O primeiro pedido após o limite passou6. As contagens ainda não tinham atualizadoDeixe folga; as contagens atualizam após cada pedido
Aparece outra mensagem7. Outra regra ou app falhou primeiroConfira se as regras do pedido estão marcadas
A mensagem mostra ' ou outro código8. Mensagem escapada duas vezesAvise o desenvolvedor do app
O pedido chegou sem verificação nenhuma9. O pedido veio de um canal que não passa pela validaçãoPedidos de POS, renovações, edições e API não são validados

1. A validação não está ativa

Instalar um app com Function de validação nem sempre a ativa. Vá em Configurações → Checkout → Regras de checkout e confira se a regra do app está listada e ativada. Se estiver desativada, nenhuma regra desse app roda em superfície alguma. No OrderRules, a lista de verificação de regras que não se aplicam começa por isso.

2. A Function travou, estourou o tempo ou as instruções

Um erro de validação sempre bloqueia o checkout. Uma execução que falhou não. Se a Function lança um erro ou excede os limites do Shopify, o checkout continua sem essa validação por padrão, e o cliente não vê nada. O app pode mudar isso com a configuração blockOnFailure ao criar a validação.

O limite que pesa na prática é de 11 milhões de instruções por execução em carrinhos de até 200 linhas. O custo cresce a cada linha do carrinho, então uma regra que funciona num carrinho de 3 itens pode falhar num de 40. Se o seu limite vale em carrinhos pequenos e falha nos grandes, essa é a causa provável. Lojistas não veem os logs de execução da Function; o desenvolvedor do app vê, no Partner Dashboard. Envie a ele o horário do pedido e o número de linhas do carrinho. A lista completa de limites está em limites de recursos da Function.

3. A regra só roda no checkout

O Shopify informa à Function onde o comprador está: alterando o carrinho ou no checkout. Muitos apps verificam certas regras só no checkout, para que adicionar ao carrinho nunca falhe por, digamos, uma data de entrega que o cliente ainda não escolheu. Essas regras não mostram nada na página do carrinho e bloqueiam no checkout.

No OrderRules, loja fechada, limites de pedidos, limites por produto e variante, quantidades mínimas e de múltiplos, e limites por tag e coleção são verificados ao adicionar itens. Limites por cliente e verificações de entrega e retirada rodam só no checkout, porque o cliente pode ainda não ter feito login ou escolhido uma data. Se você quer que o cliente saiba antes do checkout, mostre a regra na página com uma mensagem na vitrine.

4. O tema esconde ou substitui o erro

Quando uma regra rejeita um adicionar ao carrinho ou uma mudança de quantidade, o tema recebe de volta uma requisição que falhou, com a mensagem dentro. O que acontece depois é código do tema:

  • O Dawn (16.x) mostra a mensagem abaixo do botão de adicionar ao carrinho. Ele também pode trocar o botão para "Sold out" (Esgotado), e o produto parece indisponível sem estar.
  • Os botões de adição rápida nas páginas de coleção costumam mostrar só "Sold out" ou um erro genérico curto.
  • Carrinhos laterais personalizados podem ignorar o erro por completo e simplesmente não adicionar o item.

Para confirmar que é o tema: abra as ferramentas de desenvolvedor do navegador, vá à aba Network (Rede) e adicione o produto de novo. Uma requisição /cart/add.js ou /cart/change.js com falha, cuja resposta contém a sua mensagem, significa que a regra funcionou e o tema não a mostrou. Tente a mesma ação em uma prévia do Dawn sem edições. Se o Dawn mostrar a mensagem, peça ao desenvolvedor do tema para exibir o erro da requisição de carrinho que falhou.

5. O checkout expresso ignorou um atributo do carrinho

A referência de validação do Shopify observa que o checkout acelerado a partir da página do produto ignora os atributos do carrinho. Se uma regra depende de algo que o cliente escolheu na página do carrinho e salvou como atributo do carrinho, como uma data de entrega ou um bilhete de presente, um botão Buy it now ou Shop Pay na página do produto nunca o envia. Dependendo de como o app foi feito, a regra não enxerga a escolha ou bloqueia o pedido com uma mensagem "escolha uma data".

A correção está no app: salvar a escolha em cada item do pedido, o que os botões da página do produto carregam, ou exigir a escolha no checkout. O OrderRules salva no item do pedido a data de entrega escolhida na página do produto, então os pedidos do Buy it now a mantêm. Teste esse botão na sua loja antes de um dia movimentado.

6. As contagens não tinham atualizado

Uma Function não pode chamar o servidor do app durante o checkout. Ela lê contagens que o app salvou antes, e o app as atualiza após cada pedido. Por isso o primeiro checkout depois de atingido o limite pode passar, e dois checkouts no mesmo instante pela última unidade podem passar os dois. Não falta mensagem aqui; a regra viu a contagem antiga. Deixe um pouco de folga num limite que você não pode exceder e veja limites por checkout vs por cliente para entender como os limites por cliente contam.

7. Outra regra ou app respondeu primeiro

O Shopify executa todas as Functions de validação ativas, até 25 por loja, e basta uma retornar erro para bloquear o checkout. Dentro de um mesmo app, as regras costumam ser verificadas em ordem fixa. No OrderRules, uma loja fechada mostra só a mensagem de fechada, mesmo que o carrinho também esteja abaixo do mínimo. O cliente corrige uma coisa e depois vê a próxima. Veja qual mensagem o cliente vê para a ordem completa.

Se a mensagem não for do seu app, outra validação de app está bloqueando. Confira a lista em Configurações → Checkout → Regras de checkout.

8. A mensagem mostra código

Um apóstrofo que aparece como ', ou um E comercial como &, indica que a mensagem foi escapada em HTML duas vezes em algum ponto entre o app e a página. É um bug de exibição no app ou no tema, não nas suas configurações. Informe ao desenvolvedor do app a página e a mensagem exatas.

9. O pedido nunca passou pela validação de checkout

Alguns pedidos não rodam a validação de carrinho e checkout, então não há mensagem para mostrar:

  • Vendas do Shopify POS
  • Pedidos de renovação de assinatura (o primeiro checkout da assinatura é validado)
  • Edições de pedido após a compra
  • Pedidos feitos por outros apps ou integrações pela Create Order API
  • Compras de pré-venda e de experimentar antes de comprar

Rascunhos de pedido pagos pelo checkout da fatura são validados. No OrderRules, os pedidos dos canais acima não são bloqueados, mas continuam contando para os seus limites. A tabela completa está em compatibilidade e limitações.

Teste todas as superfícies em 10 minutos

Use uma loja de desenvolvimento ou um produto de teste e crie uma regra que você possa quebrar de propósito, como um máximo de 2.

  1. Página do produto: adicione 3. Observe o que o botão e a mensagem fazem.
  2. Adição rápida na coleção: adicione o produto a partir de uma página de coleção.
  3. Página do carrinho e carrinho lateral: mude a quantidade para 3.
  4. Checkout: vá ao checkout com 3 no carrinho. Você deve ver a mensagem e não conseguir pagar.
  5. Buy it now e Shop Pay: compre 3 pela página do produto com cada botão.
  6. Logado e deslogado: repita o checkout nos dois casos se usar limites por cliente.
  7. Um carrinho grande: adicione 40 linhas ou mais se a sua loja vende muitos itens pequenos.

Mantenha a aba Network aberta durante o teste. Qualquer etapa que bloqueie sem mensagem na tela é problema do tema (causa 4). Qualquer etapa que passe quando não deveria é a causa 1, 2, 5 ou 9.

Leitura relacionada

Fontes

Perguntas frequentes

As causas mais comuns: a validação não está ativada em Configurações → Checkout → Regras de checkout; a Function travou ou estourou o limite de instruções, e o checkout seguiu sem ela; a regra só roda no checkout, então nada aparece no carrinho; ou o tema captura o erro do carrinho e mostra uma mensagem genérica ou "Sold out" (Esgotado). Teste a página do produto, o carrinho e o checkout separadamente para ver qual é o caso.

No checkout, um erro voltado ao carrinho inteiro aparece na etapa atual, e um erro voltado a um campo aparece ao lado dele. Na loja online, um erro retornado ao adicionar ou alterar itens volta para o tema como uma requisição de carrinho que falhou. O tema decide se e onde mostrá-lo. Vitrines headless leem os erros do carrinho da Storefront API.

Se uma regra de validação rejeita o pedido de adicionar ao carrinho, alguns temas tratam qualquer falha como esgotado. O Dawn, por exemplo, mostra a mensagem de erro abaixo do botão e também pode trocar o botão para "Sold out". O produto não está sem estoque; a regra bloqueou aquela quantidade ou aquele carrinho. Confira qual regra se aplica ao produto.

Não por padrão. Se a execução de uma Function falha, por exemplo por tempo esgotado ou por estourar as instruções em um carrinho grande, o Shopify deixa o checkout continuar sem essa validação, a menos que o app a tenha criado com blockOnFailure ativado. O cliente não vê mensagem e o pedido passa.

A validação roda no Shop Pay, Apple Pay, Google Pay, PayPal express e Buy it now. Uma ressalva: o checkout expresso a partir da página do produto ignora os atributos do carrinho, então uma regra que depende de algo escolhido pelo cliente na página do carrinho, como uma data de entrega salva como atributo do carrinho, não a enxerga ali.

Vendas no POS, renovações de assinatura, edições de pedido, pedidos criados pela API e compras de pré-venda ou de experimentar antes de comprar não rodam a validação de carrinho e checkout, então não podem mostrar a mensagem. Rascunhos de pedido pagos pelo checkout da fatura rodam a validação.

Comparando apps?

Veja como o OrderRules se sai contra todos os outros apps do Shopify nesta categoria.

Pronto para assumir o controle dos seus pedidos?

Experimente o OrderRules grátis