---
title: "Erro de validação de carrinho ou checkout do Shopify não aparece? 9 causas e correções"
description: "Seu limite de pedido ou regra de checkout está configurado, mas o cliente não vê a mensagem, ou vê \"Sold out\" no lugar. Veja onde o Shopify mostra erros de validação, as nove causas mais comuns e como testar cada superfície."
contentType: "blog"
locale: "pt-br"
localized: true
source: "https://orderrules.com/pt-br/blog/shopify-checkout-validation-error-not-showing"
slug: "shopify-checkout-validation-error-not-showing"
date: "2026-11-21"
tags:
  - "shopify"
  - "checkout validation"
  - "shopify functions"
  - "troubleshooting"
  - "order limits"
  - "cart"
---
**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](/blog/shopify-checkout-validation-functions-block-orders).

## 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 acontece | Quem mostra a mensagem |
|---|---|---|
| **Checkout** | O 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 headless** | Os 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

| Sintoma | Causa provável | Correção |
|---|---|---|
| Nenhuma regra dispara, em lugar nenhum | 1. Validação não ativa | Ative em Regras de checkout |
| Funciona em carrinhos pequenos, não nos grandes | 2. A Function travou ou estourou as instruções | Avise o desenvolvedor do app com o horário e o tamanho do carrinho |
| Nada na página do carrinho, bloqueia no checkout | 3. A regra roda só no checkout | Esperado; avise os clientes com antecedência |
| "Sold out" ou erro genérico no lugar da sua mensagem | 4. O tema esconde ou substitui o erro do carrinho | Teste no Dawn; corrija o tratamento de erros do tema |
| Funciona pelo carrinho, não pelo Buy it now | 5. O checkout expresso ignorou os atributos do carrinho | Salve a escolha por item do pedido ou exija no checkout |
| O primeiro pedido após o limite passou | 6. As contagens ainda não tinham atualizado | Deixe folga; as contagens atualizam após cada pedido |
| Aparece outra mensagem | 7. Outra regra ou app falhou primeiro | Confira se as regras do pedido estão marcadas |
| A mensagem mostra `&#39;` ou outro código | 8. Mensagem escapada duas vezes | Avise o desenvolvedor do app |
| O pedido chegou sem verificação nenhuma | 9. O pedido veio de um canal que não passa pela validação | Pedidos 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](/docs/troubleshooting/rules-not-applying) 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](/blog/shopify-checkout-validation-functions-block-orders).

### 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](/docs/guides/storefront-messaging).

### 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](/blog/per-checkout-vs-per-customer-limits-shopify) 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ê](/blog/shopify-order-rules-recipes) 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 `&#39;`, ou um E comercial como `&amp;`, 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](/docs/guides/compatibility-and-limitations).

## 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

- [Como funciona a validação de checkout do Shopify](/blog/shopify-checkout-validation-functions-block-orders)
- [Regras que não se aplicam: a lista de verificação do OrderRules](/docs/troubleshooting/rules-not-applying)
- [Onde as regras do OrderRules são verificadas: compatibilidade e limitações](/docs/guides/compatibility-and-limitations)
- [Mensagens na vitrine](/docs/guides/storefront-messaging)

## Fontes

- Shopify.dev: [Cart and Checkout Validation Function API](https://shopify.dev/docs/api/functions/latest/cart-and-checkout-validation) (targets, etapas da jornada do comprador, execuções com falha e `blockOnFailure`, superfícies suportadas, checkout acelerado e atributos do carrinho)
- Shopify.dev: [Function APIs: resource limits](https://shopify.dev/docs/api/functions)
- Shopify Dawn no GitHub: [`assets/product-form.js`](https://github.com/Shopify/dawn/blob/main/assets/product-form.js) (tratamento de erros do adicionar ao carrinho, versão 16.2.0)
