Debug do GA4 Measurement Protocol: por que 2xx não prova nada

O GA4 Measurement Protocol retorna um status 2xx para quase tudo que você envia a ele: um evento válido, um evento com erro de digitação, um evento sem client_id, um segredo que você inventou. Então o código de status é inútil para debug. Para fazer debug de chamadas do GA4 Measurement Protocol, envie o mesmo corpo ao servidor de validação em /debug/mp/collect, leia o validationMessages que ele retorna, corrija o que ele aponta e só então confirme a chegada no DebugView ou no Realtime.

Esse último passo importa mais do que as pessoas esperam. Por quê? O servidor de validação não verifica seu segredo de API, então um payload pode passar na validação, receber um 204 do endpoint real e ainda assim nunca chegar à sua propriedade, e eu já vi uma equipe perder uma semana exatamente com isso antes de alguém pensar em copiar o segredo de novo.

Se você está conectando eventos do lado do servidor para rastrear campanhas, o guia central sobre rastreamento de UTMs de ponta a ponta cobre o que deve estar no link antes de tudo isso. Este post é sobre o momento em que você envia o evento e nada aparece.

Por que o Measurement Protocol responde 2xx para tudo

A referência do protocolo do Google é direta: o endpoint retorna um código de status 2xx se a requisição HTTP é recebida, e não retorna erro se o payload está malformado ou se os dados não são processados. A coleta funciona no modo "dispare e esqueça". Seu servidor nunca espera pelo processamento.

Nós mesmos conferimos isso. Um POST para /mp/collect com o corpo {"garbage":true}, um ID de medição falso e um segredo inventado voltou como HTTP 204 com corpo vazio. Igual a um evento perfeito.

Lógica de nova tentativa baseada em códigos de status captura falhas de rede. Nada além disso. Ela não consegue dizer que o GA4 descartou seus eventos. Para isso, você precisa do segundo endpoint.

Como usar o servidor de validação em /debug/mp/collect

O servidor de validação do Measurement Protocol fica no mesmo host. Mesma string de consulta, mesmo corpo:

curl -s -X POST \
  "https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"name":"session_start","params":{"firebase_x":1}}]}'

Ele responde 200 com um corpo JSON em vez de um corpo vazio. Esse payload de teste tem três problemas, e o servidor relata o primeiro que encontra:

{
  "validationMessages": [
    {
      "fieldPath": "client_id",
      "description": "Measurement requires a client_id.",
      "validationCode": "VALUE_REQUIRED"
    }
  ]
}

Adicione um client_id e ele passa para NAME_RESERVED em session_start; renomeie o evento e o prefixo firebase_ vem em seguida. Cada mensagem traz um fieldPath, uma descrição humana e um código. Os códigos que o Google documenta incluem VALUE_INVALID, VALUE_REQUIRED, NAME_INVALID, NAME_RESERVED, VALUE_OUT_OF_BOUNDS, EXCEEDED_MAX_ENTITIES e NAME_DUPLICATED.

Um array vazio, "validationMessages": [ ], significa que a estrutura está correta. Nada enviado para /debug/mp/collect é armazenado. Use sem dó durante o desenvolvimento; só lembre que uma chamada de debug nunca prova que os dados chegaram.

O que o servidor de validação não verifica

A maioria dos tutoriais pula esta parte. A página de validação de eventos do Google diz claramente que o servidor de validação não valida o api_secret. Em nosso teste em 22 de setembro de 2026, ele também não verificou o ID de medição: G-FAKE123 com o segredo nonsense retornou um array validationMessages vazio.

Um segredo errado passa. Um revogado também, um de outro fluxo de dados ou um erro de digitação em G-. O api_secret do Measurement Protocol é o motivo mais comum que vejo para "payload válido, nenhum dado", e você só consegue confirmar vendo um evento chegar.

A segunda lacuna é o modo de validação. Por padrão, o servidor roda no modo RELAXED, e nesse modo ele deixou passar duas coisas que os próprios limites do Google proíbem: um evento com 26 parâmetros e um valor de parâmetro com 120 caracteres. Adicione "validation_behavior": "ENFORCE_RECOMMENDATIONS" ao corpo de debug e ambos falham, com EXCEEDED_MAX_ENTITIES e VALUE_TOO_LONG. Eu sempre validaria no modo rigoroso, mesmo que a produção continue relaxada. É a diferença entre um verificador e um carimbo.

Como ver eventos de servidor no GA4 DebugView e no Realtime

Quando o payload validar, envie-o ao endpoint real e veja ele chegar. Duas visualizações funcionam para eventos de servidor, e relatórios padrão não são uma delas, já que podem ficar 24 a 48 horas atrasados.

O DebugView precisa ser ativado evento a evento. O guia de verificação do Google pede "debug_mode": 1 (ou true) nos parâmetros do evento, além de um engagement_time_msec positivo. Só eventos com esse sinalizador aparecem, então um lote em que um evento não tem o sinalizador parece meio vazio. Abra Admin, depois DebugView, e dê um minuto.

O Realtime não precisa de nada extra. Role até o cartão "Contagem de eventos por nome do evento" e procure seu evento. O Google observa que session_id e engagement_time_msec importam para a atividade do usuário aparecer no Realtime, então, se um evento valida mas o Realtime continua vazio, confira esses dois primeiro.

Mais uma ressalva do mesmo guia: para fluxos web, ele diz que um evento válido usa um client_id que o gtag.js já usou. IDs sintéticos ainda são contados, cada um como seu próprio usuário, mas nunca se juntam a uma sessão do navegador, e em um relatório construído em torno de sessões isso aparece como uma longa cauda de usuários de um evento só que você não consegue explicar até saber de onde vieram. Mais sobre isso na próxima seção. Se o que falta são dados de campanha em vez de eventos, parâmetros UTM que não aparecem no GA4 percorre o lado do DebugView desse problema.

Erros comuns de payload e o que o validador diz

A maioria dos eventos quebrados cai em alguns padrões. Aqui estão eles com o que o servidor de validação retornou quando enviamos cada um em 22 de setembro de 2026:

Duas linhas merecem um comentário. O prefixo ga_ é reservado segundo a referência, mas o validador aceitou ga_session_id nos dois modos quando testamos, então não trate um array vazio como permissão. E o limite de 100 caracteres para valores pega URLs de destino completas o tempo todo: uma página de destino com cinco tags UTM costuma passar disso.

O próprio client_id é o detalhe sutil. Qualquer string passa pela validação relaxada, mas o modo rigoroso rejeitou tanto c1 quanto elido-12-4711 com "It should be in . format". Se seus eventos precisam se costurar às sessões do navegador, envie o valor _ga real; o guia de rastreamento do lado do servidor do GA4 explica essa costura em detalhes.

Como o encaminhador GA4 da Elido e o teste de conexão usam isso

A Elido encaminha cliques em links curtos para o GA4 do lado do servidor. Você cola um ID de medição e um segredo da API do Measurement Protocol no cartão GA4 em Integrações, e daí em diante cada clique nesse espaço de trabalho vira um evento link_click:

{
  "client_id": "elido-12-4711",
  "events": [
    {
      "name": "link_click",
      "params": {
        "workspace_id": 12,
        "link_id": 4711,
        "slug": "spring-26",
        "country": "DE",
        "device": "mobile",
        "destination": "https://shop.example/spring?utm_source=newsletter",
        "engagement_time_msec": 100
      }
    }
  ]
}

O client_id é elido-<workspace>-<link>, então todo clique em um link aparece como o mesmo usuário no GA4 e nenhum deles se junta a uma sessão do navegador. Essa é a troca honesta de fazer isso sem cookie: totais e quebras por slug, país e dispositivo funcionam; contagens de usuários e funis de sessão não. País e dispositivo são parâmetros de evento simples. Registre-os antes como dimensões personalizadas. E um destination acima de 100 caracteres encontra o limite da tabela acima, então use slug ou link_id nos relatórios.

O botão de teste de conexão segue a ordem que este artigo recomenda:

Primeiro ele envia um link_click sintético, marcado com elido_test: true, para /debug/mp/collect. Se validationMessages não estiver vazio, o teste falha e mostra as descrições do Google literalmente. Se o array estiver vazio, o mesmo evento vai para /mp/collect de verdade. Abaixo do botão você vê a resposta do fornecedor (status HTTP, o endpoint de debug com seu ID de medição, mas nunca o segredo, e o corpo do Google), além de uma nota dizendo que o Measurement Protocol não verifica o segredo de API.

Então verde significa "válido, e o Google recebeu". Não "sua propriedade já tem isso". O evento de teste leva debug_mode: 1 e elido_test: true, então aparece no DebugView como link_click; o Realtime também funciona. Se você quer eventos de clique no GA4 sem uma tag em cada página de destino, crie um espaço de trabalho e aponte o cartão GA4 para uma propriedade de teste primeiro.

Uma ordem de debug do GA4 Measurement Protocol que funciona

Quando eventos do GA4 não aparecem, siga esta ordem e pare na primeira falha:

1. Envie o corpo para /debug/mp/collect com validation_behavior definido como ENFORCE_RECOMMENDATIONS. Corrija todas as mensagens.
2. Copie o segredo de API novamente em Admin, Fluxos de dados, seu fluxo web, segredos da API do Measurement Protocol. Confira se ele é do mesmo fluxo que o ID G-.
3. Envie um evento para /mp/collect com debug_mode: 1 e observe o DebugView por dois minutos.
4. Remova o sinalizador e confira o Realtime, depois dê um ou dois dias aos relatórios padrão.

O passo 2 é onde termina a maior parte do meu próprio debug. A página de solução de problemas do Google abre com as mesmas três perguntas: segredo certo, ainda válido, copiado exatamente. Quando os números finalmente fluem e ainda não batem com suas contagens de links, cliques em links curtos versus sessões do GA4 explica a diferença, e rastreamento de conversão do lado do servidor cobre os eventos de conversão que geralmente vêm em seguida. O mesmo hábito de validar e depois verificar se aplica aos outros destinos na página de rastreamento de conversões.

Relacionados no blog

• Rastreamento do lado do servidor do GA4 via redirecionamentos - credenciais, formato do payload e costura de client_id.
• Mixpanel vs GA4 para análise de links - qual ferramenta deve guardar seus dados de clique.
• Rastreamento de links no Mixpanel - o mesmo encaminhador apontado para o Mixpanel, com sua própria peculiaridade de 200 para qualquer coisa.
• Parâmetros UTM que não aparecem no GA4 - a versão de dados de campanha deste problema de debug.
• Rastreamento de conversão do lado do servidor - GA4, Meta CAPI e TikTok lado a lado.